Skip to main content

Celonis Product Documentation

Configuration of the customize metadata JSON

Important

Any references to third-party products or services do not constitute Celonis Product Documentation nor do they create any contractual obligations. This material is for informational purposes only and is subject to change without notice.

Celonis does not warrant the availability, accuracy, reliability, completeness, or usefulness of any information regarding the subject of third-party services or systems.

This functionality allows you to add custom tables and columns to the Coupa Extractor that are not supported by default.

The feature can be enabled via the advanced settings in the connection configuration. After enabling, a JSON configuration needs to be provided. This article describes the structure of this json configuration.

General Structure

The metadata JSON contains the following objects:

  • version: it is the value of Coupa API version

  • metadataSources: Contains url used to access the table over Coupa API and the table names to which the url applies.

  • resources: List of tables and custom objects

{
  "version": "R27",
  "metadataSources": [

   ],
   "resources": [
    
   ]
}

How to configure the metadata sources?

Metadata source needs to be added for each resource in the resources section. You can find the simple example of the metadataSources json below

{
 "url": "resource_name_value",
 "targetResources": [
   "display_name_value"
 ]
}

Resource_name_value and display_name_value contain the resource data and we need to add the resource name in the resource configuration (as a URL and display name of the target resource)

How to configure the resources?

Resources consist of the following sections:

  • Columns

  • NestedFields

  • NestedArrays

Following fields are required in the resources before configuring the mentioned sections

{
      "displayName": "display_name_value",
      "availableSince": "R21", 
      "resource": "resource_name_value",
......
}

displayName: custom name of the table where the resource will be extracted to

availableSince: supported version of the Coupa API

resource: resource name in the Coupa

Configuration of columns

Columns section contains all the columns we want to add to the table. It is required in the table and nested table configurations. The extractor will extract the tables’ columns which are mentioned in the columns section with the correct name and the type. The primary key should be added with the primaryKey = true value but the foreign key does not exist. The backend will add the foreign key for the nested tables. It is also possible to add the field with nested fields as a column instead of creating nested fields in the configuration. However, the values of the columns will be JSON String.

You can find the simple configuration of the column section below

{  
"resources": [
  {
      .....
      "columns": [
        {
          "name": "id",
          "type": "INTEGER",
          "primaryKey": true
        },
{
          "name": "ColumnA",
          "type": "Type"
        },
    {
          "name": "ColumnB",
          "type": "Type"
        },
    ....
      ],
      .....
   }

Configuration of nested fields

Configuring the nestedFields in the resources will let the extractor extract the nested fields of the columns in the table. You can find the simple example for the nested field below

{
  "resources": [
    { 
     ............
      "nestedFields": [
        {
          "name": "column_name_nested_field",
          "pathToField": [
            "nested_field" 
          ],
          "parentName": "column_name",
          "type": "TYPE"
        }
      ]
    ............
  ]
}

column_name_nested_field: it is the name for the new column of the nested field. Please follow the structure (column name + _ + nested field name)

column_name: column name of the table which has nested fields

nested_field: nested field name

Configuration of nested arrays

It is possible that the table data has columns with the list of objects data. It would be not possible to configure these data with nested fields which is why we need to create a new table where we will able to list all the objects. In the configuration, we are able to add nested arrays which will make us extract that type of columns as nested tables. NestedArrays have a one-to-many relationship with the main table and we can also increase nestedness by adding a new nested array to the nested array as well. You can find the simple JSON example below

{
  "resources": [
    .......................
      "nestedArrays": [
        {
          "nestedTableName": "main_table_name_column_name",
          "path": [
            "column_name"
          ],
          "columns": [
            {
              "name": "id",
              "type": "INTEGER"
            },
         .......
          ],
          "nestedFields": [
              ...........
          ]
       "nestedArray": [
..........
   ]
        }
      ]
     ...........
    }
  ]
}

main_table_name_column_name: it is the name for the nested table. Please follow the structure (display name of the table + _ + column name)

column_name: the column name in the table which has the list of objects

Configuration of the nested fields and the columns are already mentioned. In the nested array, we need to mention all the fields which have nested fields in the nested fields section. Otherwise, we should add them to the column section to be able to see them in the nested table. If the columns of the nested table will have a list of objects, we will need to add a new nested array to the nested array configuration.

JSON example for payment API

You can use the following example JSON data for the payment API to customize your metadata JSON

{ 
  "version": "R27",
  "metadataSources": [
{
     “url”: “payments”,
      “targetResources”: [
        "payments"
      ]
}
   ],
  "resources": [
    {
      "displayName": "payments",
      "availableSince": "R21",
      "resource": "payments",
      "filteringEnabled": true,
      "fieldSelectionEnabled": true,
      "paginationEnabled": true,

      "columns": [
        {
          "name": "id",
          "type": "INTEGER",
          "primaryKey": true
        },
{
 "name": "created-at",
 "type": "DATETIME"
},
{
 "name": "updated-at",
 "type": "DATETIME"
},
{
 "name": "status",
 "type": "STRING"
},
    {
 "name": "pay-from-total",
 "type": "DECIMAL"
},
    {
 "name": "pay-to-total",
 "type": "DECIMAL"
}
      ],
      "nestedFields": [
        {
          "name": "created-by_email",
          "pathToField": [
            "email" 
          ],
          "parentName": "created-by",
          "type": "STRING"
        },
{
          "name": "created-by_employee-number",
          "pathToField": [
            "employee-number" 
          ],
          "parentName": "created-by",
          "type": "STRING"
        }
      ]
}