This documentation supports the 20.08 version of BMC Helix Platform. 
To view an earlier version, select 20.02 from the Product version menu.

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.

A document definition defines the communication between two third-party modules. You can define a document definition when you communicate with a third-party module 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.


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, click New.
  4. In the Create Document Definition window, specify the properties for the document definition.
    The following table provides information about the properties: 

    Document NameType a unique name that identifies the document. 
    Document Schema

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

    Example 1:


    Example 2:

    Scope/Customization OptionsTo define the scope of the document definition set the following options:
    • (Default) Application/Library—Limits the use of the definition within the same application or library. 
    • Public—Enables the definition to be used by all applications or libraries and allows customization to this definition.
  5. Click Save

Where to go from here

Use the created document definition to access complex objects, array of objects, 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.Adding process variables

Create data for the structure defined by document definition.

Creating a document instance

Was this page helpful? Yes No Submitting... Thank you