Jumpstart your configuration by creating a custom extractor by uploading the extractor template in Celonis that you can download here. If you do not want to use the extractor template in Celonis and prefer to manully configure your extractor, proceed to the next section.
In the New custom REST API extractor window, select the "Import From File" option and upload the template.
After the extractor is created, you will find that the Endpoint has been configured for you, including "elements", "facets", and an example "hierarchy" for the Processes facet.
To create the connection with your environment, go to the “Data connection” tab and fill in the empty fields using the values listed below.
| Field Name | Details | Expected Value |
|---|---|---|
| Name | The name of your connection. | Not prefilled, free-text value. |
| API URL | URL that identifies the API provider. | Enter the URL for your specific region:
|
| Tenant ID | This is a unique ID to identify your data location. Currently it can only be found by opening either the Navigator or Admin App and checking the URL of the page after it has fully loaded. | Not prefilled, you can find it via: the first GUID of the Navigator URL: https://navigator.symbio.cloud/celonis/c592ade4-4a5a-4804-a6e0-267f6a164fc6or the “tenant” section of the Admin App URL: https://admin.symbio.cloud/?company=celonis&tenant=c592ade4-4a5a-4804-a6e0-267f6a164fc6 |
| API Key | The API key can be generated using the Admin App within the “Reporting” section. | Format of theAPI key. Not prefilled. |
Once your connection is configured, you will need to wait for the fullfetch cycle to run overnight before any data is shown or the nested tables are displayed. See After the connection is created below for more inforation.
For more information on setting up this connection, see Creating a custom REST API extractor / using a pre-built template.
This section provides an example of how a custom connection would look when using the Reporting API.
In Data integration, the user can go to the Extractor builder and build their own extractor based on an API. Here, we will use our API to set up the connection.
To use the API connection, your configuration should look like this:
Select “API Key Authentication” as the Authentication Method.
In the API URL field, add the applicable value from the table below based on your region.
The server region of the reporting API will match the region of your Admin App URL.
| Domain Region | Value | Description |
|---|---|---|
| Europe | https://api-reporting.symbio.cloud/ | For customers deployed to the Europe region. |
| U.S. | https://api-reporting.us-1.symbio.cloud/ | For customers deployed to the U.S. region. |
| Japan | https://api-reporting.jp-1.symbio.cloud/ | For customers deployed to the Japan region. |
In the Pagination Method section, enter "skip" as Offset Parameter and "take" as Limit Parameter. Then set a default limit. Note that the maximum limit is 100, which will be applied if no limit is set.
After creating a successful connection, you will initially not see any data and you will not find all the nested tables. Since the API is based on the fullfetch cycle, you will need to wait overnight before you start to see data coming through. Check the extractor after the cycle has been run and then click the Generate Response button to view the nested tables.
Make sure that “items” is selected from the Response root dropdown before generating the response. The default value for this field is “Entire Response (default)” which would cause further nesting of all tables and result in the transformation SQL not working properly.
After running the response, you may encounter issues with your results.
In some cases, you might see that your extraction failed even though your extraction connection test was successful. You might see a warning in your logs that looks like this:
To resolve this issue, add more time to the Socket Timeline field within your extraction configuration. This should allow you to extract the data.
Clicking Generate Response may result in incomplete JSON files being created. For example, the API may return five JSONs for the “automation” facet, which would all be missing properties, such as those from the “processes” facet items. This could result in attributes (such as shortDescription) or even full tables (e.g. elements$versions$related$locations) missing from the files following extraction.
For example, if you fetch all Elements but notice that the Attribute myNewAttribute is missing even though it is present in one or more Elements:
To resolve this issue, you will need to manually add the missing Attribute. The easiest way to do this is by copying an existing Attribute in the Preview window and then changing its Name and Value to match the missing Attribute:
After generating the response, you may also need to set the Primary Keys for some of your generated extraction tables (see the list below). To set the Primary Keys, expand the table configuration and then select the Primary Key checkbox for each column that you want to assign.
Assigning Primary Keys creates an additional property within each Child table that can be used to refer back to the Parent item. For example, selecting id from elements table as a Primary Key will create a new property named elements_id in elements$content and elements$versions.
The following properties should be assigned as Primary Keys in the corresponding table:
- “elements”
- “id”
- “elements$content”
- The generated “elements_id”
- “id”
- “versionId”
- “elements$versions”
- The generated “elements_id”
- “versionId”
- “elements$versions$content”
- The generated “elements$versions_elements_id”
- The generated “elements$versions_versionId”
- “id”
- “versionId”
With this data connection, you can then create transformation to make usable data tables. Here is an example transformation script:
CREATE OR REPLACE VIEW `Element` AS
SELECT
/* Unique ID for the Element */
CASE
WHEN `T`.`source_table` = 'elements'
THEN `T`.`original_id` /* For non-versionable elements */
WHEN `T`.`source_table` = 'elements$versions'
THEN `T`.`original_version_id` /* For versionable elements */
WHEN `T`.`source_table` IN ('elements$content', 'elements$versions$content')
THEN `T`.`original_id` /* For content items (their own 'id' is unique GUID) */
END AS `_id`,
`T`.`source_table`, /* Helps identify where the record originated ('elements', 'elements$versions', 'elements$content', 'elements$versions$content') */
`T`.`original_id`, /* Original 'id' from the source table (PK for elements and content) */
`T`.`original_version_id`, /* Original 'versionId' from elements$versions (PK for versions) */
`T`.`parent_fk_id`, /* Original FK from content tables to their parent element/version */
`T`.`supportsVariants`,
`T`.`supportsVersions`, /* FALSE for content objects */
`T`.`containerPermaLink`,
`T`.`facetName`,
`T`.`permaLink`,
`T`.`type`,
`T`.`variantId`,
`T`.`creationId`,
/* Common Attributes (renamed for consistency) */
`T`.`attributes_changedOn`,
`T`.`attributes_createdOn`,
`T`.`attributes_gotoUrl`,
`T`.`attributes_name`,
`T`.`attributes_state1`,
`T`.`attributes_description`,
`T`.`attributes_isReleased`, /* Attributes specific to elements$versions (will be NULL for non-versioned elements and all content) */
`T`.`attributes_isLastInProcessOrReleased`,
`T`.`attributes_majorVersion`,
`T`.`attributes_minorVersion`,
`T`.`attributes_reviewDate`,
`T`.`attributes_validFrom`,
`T`.`attributes_validUntil`,
`T`.`attributes_version`,
`T`.`attributes_reasonForRevision`,
`T`.`attributes_imageUrl`,
`T`.`attributes_stereotype`,
`T`.`attributes_id_from_version`, /* The 'id' attribute from versions */
`T`.`stereotype` /* The 'stereotype' column from elements$versions */
FROM (
/* Data from 'elements' table (non-versionable parent elements) */
SELECT
'elements' AS `source_table`,
`e`.`id` AS `original_id`,
'00000000-0000-0000-0000-000000000000' AS `original_version_id`,
NULL AS `parent_fk_id`,
`e`.`supportsVariants`,
`e`.`supportsVersions`,
`e`.`containerPermaLink`,
`e`.`facetName`,
`e`.`permaLink`,
`e`.`type`,
`e`.`variantId`,
`e`.`creationId`,
`e`.`attributes$changedOn$127` AS `attributes_changedOn`,
`e`.`attributes$createdOn$127` AS `attributes_createdOn`,
`e`.`attributes$gotoUrl$1033` AS `attributes_gotoUrl`,
`e`.`attributes$name$1033` AS `attributes_name`,
`e`.`attributes$state1$127` AS `attributes_state1`,
`e`.`attributes$description$1033` AS `attributes_description`,
NULL AS `attributes_isReleased`,
NULL AS `attributes_isLastInProcessOrReleased`,
NULL AS `attributes_majorVersion`,
NULL AS `attributes_minorVersion`,
NULL AS `attributes_reviewDate`,
NULL AS `attributes_validFrom`,
NULL AS `attributes_validUntil`,
NULL AS `attributes_version`,
NULL AS `attributes_reasonForRevision`,
NULL AS `attributes_imageUrl`,
NULL AS `attributes_stereotype`,
NULL AS `attributes_id_from_version`,
NULL AS `stereotype`
FROM `elements` AS `e`
WHERE
`e`.`supportsVersions` IS FALSE /* Only non-versionable top-level elements */
UNION ALL
/* Data from 'elements$versions' table (versionable parent elements - specific versions) */
SELECT
'elements$versions' AS `source_table`,
`ev`.`id` AS `original_id`, /* This is the FK to elements.id, but versionId is the primary identifier for this record */
`ev`.`versionId` AS `original_version_id`,
NULL AS `parent_fk_id`,
NULL AS `supportsVariants`,
NULL AS `supportsVersions`,
`ev`.`containerPermaLink`,
`ev`.`facetName`,
`ev`.`permaLink`,
`ev`.`type`,
`ev`.`variantId`,
`ev`.`creationId`,
`ev`.`attributes$changedOn$127` AS `attributes_changedOn`,
`ev`.`attributes$createdOn$127` AS `attributes_createdOn`,
`ev`.`attributes$gotoUrl$1033` AS `attributes_gotoUrl`,
`ev`.`attributes$name$1033` AS `attributes_name`,
`ev`.`attributes$state1$127` AS `attributes_state1`,
`ev`.`attributes$description$1033` AS `attributes_description`,
`ev`.`attributes$isReleased$127` AS `attributes_isReleased`,
`ev`.`attributes$isLastInProcessOrReleased$127` AS `attributes_isLastInProcessOrReleased`,
`ev`.`attributes$majorVersion$127` AS `attributes_majorVersion`,
`ev`.`attributes$minorVersion$127` AS `attributes_minorVersion`,
`ev`.`attributes$reviewDate$127` AS `attributes_reviewDate`,
`ev`.`attributes$validFrom$127` AS `attributes_validFrom`,
`ev`.`attributes$validUntil$127` AS `attributes_validUntil`,
`ev`.`attributes$version$127` AS `attributes_version`,
`ev`.`attributes$reasonForRevision$127` AS `attributes_reasonForRevision`,
`ev`.`attributes$imageUrl$127` AS `attributes_imageUrl`,
`ev`.`attributes$stereotype$127` AS `attributes_stereotype`,
`ev`.`attributes$id$127` AS `attributes_id_from_version`,
`ev`.`stereotype`
FROM `elements$versions` AS `ev`
WHERE
`ev`.`versionId` IS NOT NULL /* Only valid versions */
) AS `T`;
CREATE OR REPLACE VIEW `Content` AS
(
SELECT `ec`.`elements_id` as `parent_id`, '00000000-0000-0000-0000-000000000000' as `parent_version_id`, `e`.`original_id` as `content_id`,
case
when `e`.`original_version_id` is null then '00000000-0000-0000-0000-000000000000'
else `e`.`original_version_id`
end as `content_version_id`,
`ec`.`ordering` as `sorting`
FROM `elements$content` as `ec`
LEFT JOIN `Element` as `e`
ON `ec`.`id` = `e`.`original_id`
AND (
(`ec`.`versionId` IS NULL AND (`e`.`original_version_id` IS NULL or `e`.`original_version_id` = '00000000-0000-0000-0000-000000000000'))
OR
(`ec`.`versionId` IS NOT NULL AND `ec`.`versionId` = `e`.`original_version_id`)
)
WHERE `e`.`original_id` IS NOT NULL
UNION ALL
SELECT `evc`.`elements$versions_elements_id` as `parent_id`, `evc`.`elements$versions_versionId` as `parent_version_id`, `e`.`original_id` as `content_id`,
case
when `e`.`original_version_id` is null then '00000000-0000-0000-0000-000000000000'
else `e`.`original_version_id`
end as `content_version_id`,
`evc`.`ordering` as `sorting`
FROM `elements$versions$content` as `evc`
LEFT JOIN `Element` as `e`
ON `evc`.`id` = `e`.`original_id`
AND (
(`evc`.`versionId` IS NULL AND (`e`.`original_version_id` IS NULL or `e`.`original_version_id` = '00000000-0000-0000-0000-000000000000'))
OR
(`evc`.`versionId` IS NOT NULL AND `evc`.`versionId` = `e`.`original_version_id`)
)
WHERE `e`.`original_id` IS NOT NULL
);With the connection and transformation set up, you then are able to make use of the data within your Analytical tools. Here is an example of how it would look using Celonis Views.
