Defining a document schema

A document definition is a schema with fields defined in JSON format. You create a document definition to access individual attributes within a metadata object and then use those attributes in an expression for a process. A document definition supports only JSON key-value pairs to access attributes, such as a complex object, an array of objects, an array of strings, or nested complex objects.


Related topics

Creating-or-modifying-view-definitions

A document definition defines the communication between two third-party modules. When you communicate with a third-party module, you can define a document by using custom actions or connectors. The document definition enables you to access the attributes returned by the custom actions or connectors and use these attributes as an input or output within a process.

Example

Consider a scenario where you use a JIRA connector to create a new record instance when a JIRA issue is created. The connector action returns a JSON key-value pair as a result. You can use an Object type variable to access the JSON result, but the Object type variable does not allow you to access specific attributes within this result. 

To overcome this issue, you create a document definition to access each attribute within the JSON key-value pair and create a new record instance.

To create a document definition

  1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab. 
  2. Select the application for which you want to add a document definition.
  3. On the Documents tab, and click New.

  4. Specify the properties for the document definition.
    The following table provides information about the properties: 

    Property

    Description

    Example

    Name

    Type a unique name that identifies the document. 

    233_Document definition example.png

    Document schema

    Provide a document schema in JSON format that defines the property structure of the document definition.

    Example 1:

    {
    "status":""
    }

    Example 2:

    {
      "status":"",
      "error":
       {
         "errorCode":"",
         "errorMessage":""
        }
    }

    Scope/Customization options

    Define the scope of the document definition by setting the following options:

    • (Default) Application/Library—You can use this option to limit the use of the definition within the same application or library. 
    • Public—You can use this option to enable the definition to be used by all applications or libraries and allows customization to this definition.
  5. Click Save. 

To copy a document definition

You can reuse an existing document definition by copying it within the application or to a different application or library.

  1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
  2. Select the application or library from which you want to copy the document.
  3. Click Documents, select the document definition that you want to copy, and click Copy.

  4. In the Copy definition dialog box, enter the following details: 

    • From Target application/library, select the target application or library where you want to copy the document.
    • In the Definition name field, type a name for the document definition. 

    22_1_Copy record definition.png

  5. Click Save.

The copied document is saved in the target application.

Where to go from here

Use the information in the following table to navigate to the topic relevant to your goal. 

Action

Reference

Use the created document definition to access complex objects, an array of objects, an array of strings, and nested complex objects within the metadata object and use these objects as input or output to an expression within a process.

Create data for the structure defined by the document definition.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*