Create a digital interface form

  • Release version: Xanadu
  • Updated August 1, 2024
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Create a digital interface form

    This form enables ServiceNow customers to define and document digital interfaces within Enterprise Architecture (formerly Application Portfolio Management). It supports managing integration points by capturing essential metadata about each digital interface, facilitating better governance, tracking, and collaboration across business and IT teams.

    Show full answer Show less

    Key Features

    • Identification and Naming: Assign a unique, descriptive name and an automatically generated interface number (with a DINTF prefix) to distinguish each digital interface.
    • Provider and Interface Type: Specify the business application providing or owning the interface, or leave empty for external open interfaces. Classify interfaces by type (Open API, Partner API, Internal API) to indicate accessibility and usage restrictions.
    • Hierarchy and Versioning: Link interfaces to parent interfaces if part of a bundle or composition, and track versions to manage interface evolution and compatibility.
    • Life Cycle Management: Document the life cycle stage (Ideation, Design, Deploy, Operational, End of Life) and detailed statuses within each stage to represent the interface’s current operational condition.
    • Model Tracking: Optionally associate an interface with a model ID referencing API models or types from the Application Model table, enhancing classification and reuse.
    • Detailed Descriptions: Include high-level design and usage information, value propositions, and version-specific capabilities to assist architects and owners in decision-making.

    Ownership and Support

    • Business and IT Owners: Identify the responsible business and IT individuals accountable for the digital interface.
    • Support Contacts: Record the Subject Matter Expert and support group responsible for ongoing interface maintenance and issue resolution.

    Functional and Technical Details

    • Protocol: Specify the communication protocol used by the interface (e.g., REST, SOAP, LDAP), with flexibility to customize or extend the list.
    • Message Format: Define the message format (e.g., JSON, XML, CSV), also customizable to fit organizational standards.

    Authentication and Authorization

    • Authentication Type: Select from standard authentication mechanisms such as Basic Auth, OpenID Connect, Certificate, WS-Security, LDAP, or others as needed.
    • Authorization Type: Choose the authorization method used (e.g., OAuth 2.0 Token, JWT, SAML 2.0 Token), including options for no authorization or custom types.

    Activity Tracking

    Capture work notes and comments to document interface-related activities, updates, and communications, supporting transparency and auditability.

    Practical Benefits

    By using this digital interface form, ServiceNow customers can comprehensively document integration interfaces, enhance visibility across teams, ensure proper ownership and support, enforce governance policies, and facilitate the reuse and management of APIs and services within their enterprise architecture.

    Create a digital interface for an integration in Enterprise Architecture (formerly Application Portfolio Management).

    Digital Interface form fields

    Field Description
    Name Unique and meaningful name of the digital interface. Enter a descriptive name that reflects the purpose of the interface.
    For example, a Customer Management application might expose multiple digital interfaces, such as:
    • Customer Profile API — provides customer identity and profile information
    • Customer Order Service — supports order creation and status updates

    Even though all interfaces are provided by the same application, each interface represents a different interaction contract and can be consumed independently by multiple applications.
    Number Number of the digital interface. This field is automatically generated with the DINTF prefix and can’t be edited.
    Provider Business Application Name of the provider business application that provides, manager, and owns the interface.
    Note:
    This attribute can be empty if there is no business application in your repository. If you are using open interfaces such as Weather or Financial Service, you are only aware of the interface and track it without a related business application.
    Interface Type Type of API used by the interface. It helps to track whether the API is Public or Open.
    Note:
    For Public or Open APIs, there won’t be any Provider Business Application unless the Organization exposes it as an open interface.
    Use the following options:
    • Open API
    • Partner API
    • Internal API

    Public or Open APIs are available to anyone and can be used without any restrictions or license agreements.

    Internal or Private APIs are available to authorized (technical) users only and can be used without any usage restrictions and regulations.

    Partner APIs are available to authorized partners of an API provider. Usually, these APIs have special terms and conditions for usage.
    Parent Name of the parent interface.

    Often, interfaces are bundled or part of a composition. As you can reference a digital interface on the digital integration, use the parent interface. The digital interfaces related to the parent interface are listed in the related list of the interface.
    Version Version of the interface. This field helps you to track which digital integrations are using which version of an interface.
    Life Cycle Stage Life cycle stage of the interface. Use the following options:
    • Ideation
    • Design
    • Deploy
    • Operational
    • End of Life
    Life Cycle Stage Status Life cycle stage status of the interface. Each of the main life cycle stages can have one or more life cycle stage statuses. For example, a digital Interface in the operational stage might change status over time from In Use to In Maintenance to Pending Retirement. Use the following options:
    • Ideation: Under Evaluation, Pilot
    • Design: Chartered, Design, Build
    • Deploy: Test
    • Operational: In Use, In Maintenance, Pending Retirement
    • End of Life: Retired, Obsolete
    Model ID Model ID of the interface. This field helps you to track the interface model.

    This is a reference to the Application Model table where you can manage your own variants of API models or types. For example, Table API, Attachment API, Aggregate API, and Process APIs. This optional field can be used to track the interface model. Depending on your use case, you can add new models and model categories.
    Description Description of the digital interface. Provide the high-level design aspects of the interface.

    You can provide the details such as how the digital interface adds value, how it should be designed, and how it’s intended to be used.

    You can also describe different changes and capabilities according to version of the interface. It helps the Application owners and Architects to decide which interface version they want to use.
    Table 1. Owners section fields
    Field Description
    Business Owner The owner of the business function, who owns the digital interface. It can be the same person who owns the parent business application.
    IT Owner The owner within the IT organization, who owns the digital interface. It can be the same person who owns the parent business application.
    Supported By Name of the Subject matter Expert (SME) or individual who provides support to the digital interface.
    Support Group Name of the group that provides support to the digital interface.
    Table 2. Functional section fields
    Field Description
    Protocol Type of protocol used by the interface. API Protocols are the specifications that regulate the application. These protocols are used to integrate application programming interfaces with their software. Choices include REST, SOAP, LDAP, and so on.
    Note:
    This list is a non-exhaustive list and can be extended by adding your preferred values or hide the provided values.
    Message Format Format of the message in the interface. Choices include JSON, XML, CSV, and so on.
    Note:
    This list is a non-exhaustive list and can be extended by adding your preferred values or hide the provided values.
    Table 3. Authentication section fields
    Field Description
    Authentication Type Type of authentication used to authenticate the interface.
    Use the following options:
    • Basic Auth
    • OpenID Connect
    • Certificate
    • WS-Security
    • LDAP
    • None
    • Other

    You can use the system-provided authentication types or add yours.
    Authorization Type Type of authorization used to authorize the interface.
    Use the following options:
    • OAuth 2.0 Token
    • JWT Web Token
    • SAML 2.0 Token
    • Other
    • No authorization

    You can use the system-provided authentication types or add yours.
    Table 4. Activities section fields
    Field Description
    Work notes Comments about the interface.
    Create or update a digital interface