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 Celonis Platform. 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.

Create application and grant API permissions

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

  1. Click Admin & Settings and select Applications.

  2. Click Add New Application - OAuth client and save the created client for use later.

    When creating your OAuth client, use the following configurations:

    • Authentication method: Client secret post

    • Scopes to select:

      • audit.log:read (for the Audit Log API)

      • platform-adoption.tracking-events:read (for the Studio Adoption API)

      • team.login-history:read (for the Login History API)

  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 OAuth client now has the relevant API permissions.

    To obtain an access token, please use the obtained client credentials with the endpoint:

    https://TEAMNAME.CLUSTER/oauth2/token

Tip

Alternatively, you can create an application key and assign the following permissions: Audit Log API, Login History API, and Studio Adoption APIs.

For more information, see: Application keys.

Test API with Swagger

You can now test your APIs with Swagger UI. To do this, you need your team name and environment cluster and your OAuth client 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. When using an OAuth client: Enter ‘Bearer’ followed by a space and then copy the access token you obtained for the client.

    When using an application key: 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.

Creating an extractor for APIs

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:

      When using an OAuth client: Select OAuth2 (Client credentials). Enter https://[Your Team].celonis.cloud/oauth2/token for the Get Token Endpoint. Add an additional parameter with the key ‘scope’. The value should be the space-delimited scopes that you need (e.g. ‘audit.log:read team.login-history:read platform-adoption.tracking-events:read’’ for the Audit Log, Team Login History and Studio Adoption APIs).

      When using an application key: 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.

Creating an extraction

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.