Skip to main content

Celonis Product Documentation

Connecting audit log, login history, and studio adoption APIs to Celonis Platform

Within Admin & Settings you can view your audit log, team login history, and studio adoption statistics. However, these views are limited with standardized user interfaces. To run more in-depth analysis of this data, you can connect to their respective APIs and then use a data extractor to feed this information back into the . This then lets you create your own views in Studio.

To connect to the APIs and create an extractor, follow these procedures in order:

Once the data is extracted, you can then create a data model using this data. You are then ready to go to Studio and create a view using the data from the API.

To start, you need to create an application key in your team and then grant this key API permissions.

  1. Click Admin & Settings and select Applications.

  2. Click Add New Application - Application Key and save the created key for use later.

  3. Click Permissions and edit Team permissions.

    Edit_team_permissions.png
  4. Assign Audit Log API, Login History API, and Studio Adoption APIs permissions as required.

    assign_api_permissions.png
  5. Click Save.

    The application key now has the relevant API permissions.

You can now test your APIs with Swagger UI. To do this, you need your team name and environment cluster and your application key from the earlier procedure. You can find your team name and environment cluster from any URL, for example from the Permissions page from the procedure above.

https://TEAMNAME.CLUSTER/ui/team/permissions

With your team name and environment cluster, you can then access the Swagger UI using this URL:

https://TEAMNAME.CLUSTER/swagger-ui/index.html?configUrl=/log/v3/api-docs/swagger-config

Once on the Swagger UI, follow these steps to test your API:

  1. Click Authorize.

  2. Enter 'AppKey' followed by a space and then copy your application key from the earlier procedure. For example:

    AppKey XxxxxxAxxxxBxxxxCxxxXBBBB
    authorization_key.png
  3. Click Authorize. Once authorization is successful, click Close.

  4. Expand the GET call for the API you want to test and click Try it out.

    expand_and_try_it_out.png
  5. Click Execute.

    You will now see the response from the API, including the header that shows the AppKey Token and the URL.

After testing your APIs, you now need to create an extractor. This extractor pulls detailed information from your team (via the API), allowing you to add this to your Studio views.

The extractor you create in the following steps is without both pagination and headers:

  1. From your team, click Data - Data Integration.

  2. Click New Data Pool - Create from scratch , add a name, and then click Save.

  3. From the data integration diagram, click Connect to Data Source and then select Connect to Data Source.

    connect_to_data_source.png
  4. Click Custom and then click the plus icon.

    Here you have three options:

    1. Build a new Extractor.

      create_custom_data_extractor.png
    2. Customize a Celonis extractor.

    3. Import from File (For Audit logs with pagination use this JSON template, this template can also act as the foundation for the Login Log API and the Adoption API).

    When building a new extractor using the four stage wizard, enter the following information:

    • Extractor name: This can be custom to your extractor.

    • Connection Parameters - Edit API URL: Enter your Celonis team URL in the following format - https://[Your Team].celonis.cloud

    • Authentication Methods: Select API Key Authentication and enter 'Authorization' in the API key header field.

    • Define Endpoints: Configure a new endpoint and enter an endpoint name.

    • Endpoint Configure Request: In URL enter {Connection.API_URL}/[Enter what is shown in the Swagger doc URL after celonis.com.cloud]

      So the final text could read: 

      {Connection.API_URL}/log/api/external/audit?Request parameters and Headers can be completed after as needed).{Connection.API_URL}/log/api/external/audit?
    • Endpoint Pagination Method: Select No Pagination (this will default to 200 rows).

      Note

      To configure pagination for all data (200 rows and above):

      • Select Page-by-Page pagination.

      • Enter "pageNumber" in the page parameter field.

      • Ensure "0" is shown in the First Page Index field.

      • Select “totalCount” in the optional Total Size Field in Response dropdown menu. This may only be visible after you have built the response, so come back after if this is the case.

    • Configure Response: Use the sample from your source system and add a new data source. When prompted for an API field key, enter the one used in step 2 of the Swagger test procedure. For example:

      AppKey XxxxxxAxxxxBxxxxCxxxXBBBB
    • Optional: Select “content” from the Response Root dropdown menu. This ensures you only push “Content” data into the data model and will remove columns such as pagesize, pagenumber, totalcount that may not be relevant.

  5. Click Save.

  6. Click Build Response.

  7. Click Finish.

Once your extractor is built, you can configure delta loads by following these steps:

  1. Click Add Extraction.

  2. Click on the Parameters tab.

  3. Click New Parameters and populate and save the parameters as follows:

    Placeholder: LastUpdated

    Name: Last Updated

    Type: Dynamic

    Table: AuthenticationEvents

    Column: timestamp

    Default value: 01/01/2000, 00:00:00

  4. Click on the Tab configuration tab and scroll to Delta Filter Statement and add the following:

    = from = <%=LastUpdated%>

  5. Now add a data model, a data model load and a schedule following the user interface.