Creating an extended integration for Quip users (OAuth)

Sync Quip with Oomnitza to gain visibility of users and SaaS users and transform data into consumable information and actionable insights.

Automate business processes such as:

• Creating, adding and removing users from a folder
• Loading user details
• Deactivating SaaS users

  Contents

1. Before you start
2. Adding credentials in Oomnitza
3. Adding your Quip URL as a global variable
4. Creating the user integration
5. Creating custom mappings
6. Creating workflows

Before you start

To easily find the records that are uploaded to Oomnitza, it's best practice to create a dedicated user account for each integration. This will make it easier for you to retrieve the records that are uploaded to Oomnitza from the vendor application. 

Creating integration users 

To sync Quip with Oomnitza, you must retrieve the following information from Quip:

• OAuth credentials (Client ID and secret and Quip or Quip VPC URL)
• Your Quip or Quip VPC URL
• Your Quip Company ID

See License requirements for accessing Quip's APIs.

Retrieving connection information from Quip

To create an API key, you must be an administrator. And, to access to the Admin API, your admin must add you to the Admin API Users list in the Admin Console. See OAuth Process.

To get your Client ID and secret, complete the following steps:

1. Log in to the Quip admin console.
2. Click Settings.
3. Click Integrations.
4. Click New API Key.
5. Name your API key and enable the User Read, User Manage, User Write, Admin Read, Admin Write, and Admin Manage scopes.
6.  Copy the client ID and secret.

See Quip API Documentation: Create an API Key.

Quip URL. The default URL for Quip is https://platform.quip.com. However, if you're a VPC customer, use one of the following URI formats depending on the VPC URL assigned to your company:

• https://platform.<customername>.onquip.com
• https://platform.quip-<customername>.com

Quip Company ID. Go to Settings > Site Settings. The company ID is listed under the Site profile.

Adding credentials to Oomnitza

Make life easier and add your credentials to Oomnitza before you create the integration.  

1. In Oomnitza, click Configuration > Security > Credentials.
2. Click Add new credential (+).
3. Search for the integration, and then click the forward arrow > to select the integration.
4. Enter your client credentials and any other additional information.
5. Click Authenticate. You are prompted to log in to authorize your request.
6. Click CREATE.

1. Add the information details.
2. Click the AUTHORIZATION tab.
3. Ensure that OAuth 2.0 is selected as the authorization type.
4. Ensure that Quip is selected from the SaaS list.
5. Complete these actions:
   • Enter your client ID.
   • Enter your client secret.
   • Enter your Quip API URL.
6. Click Authenticate. 
7. Click CREATE. 

Next

You use the credentials that you added to create a user integration and create workflows in Oomnitza.

Creating the user integration

1. In Oomnitza, click Configuration > Integrations > Overview.
2. Click Block view .
3. On the Integrations page, scroll down to the Extended section for user integrations.
4. Click NEW INTEGRATION.
5. In the sidebar, search for the integration.
6. Click ADD.

Integration details overview

More information is provided about the following fields to help you complete the integration:

• User only. Add user records.
• User plus SaaS user. Add user and SaaS user records. 

The benefit of adding SaaS user records is that you can run a workflow to validate the status and activity of SaaS users and retrieve information such as the role of the SaaS user. The information that can be retrieved depends on whether SaaS user workflows are available for the integration. 

Installation types

• Cloud. Store credentials in the Oomnitza cloud.
• Local. Store credentials locally. If you want to sync Oomnitza with vendor applications that require AWS or OAUTH authentication, select cloud as the type of installation. Local installations don't support AWS and OAuth authentication. 

Integration preferences

• Create & Update. Add and update records.
• Create only. Add records.
• Update only. Update records.

Editing the integration details

When you edit the Integration details section, you can select the name or names of integration contacts.  Integration contacts will receive an in-app notification and an email, when the integration fails, when the integration fails to complete within 24 hours, or when the scheduled integration fails to run.

1. Click Edit .
2. Make your changes.

Editing the credential details

If you selected Cloud as the installation type, choose one of the following options:

• Select the credentials that were created for the integration.
• Edit the credentials that were created for the integration.
• Create new credentials

Scheduling the integration

By default, data is synced once every day. Change the interval or the time so that the data is streamed when your system isn't busy.

1. Click Edit .
2. Make and save your changes.

Mapping fields to Oomnitza

To map the fields to Oomnitza, click Edit .

  Select Edit integration to add rules for syncing data. Filtering integration results.  
 

You can add new fields to your integration by selecting Add new field   on the mapping page. 
Creating custom API fields. 

Creating custom mappings

Map the Quip fields to Oomnitza fields and create custom mappings to get the user information that you need.

Complete these actions:

1. Click Smart Mapping to automatically detect appropriate mapping fields. Values from the integration can also be dragged to the appropriate field on the Oomnitza side, or selected from the integration field dropdown.
2. Create custom mappings to map the Quip User Id to Oomnitza. 
   1. Click the down arrow on the Id field.
   2. Select Add new Oomnitza users field.
   3. Change the name of the field to Quip User Id.
   4. Select the Unique checkbox.
   5. Click CREATE. 
3. Ensure that the Email is mapped to the
   1. Oomnitza Username field. 
   2. Oomnitza Email field.
4. Select the Oomnitza Role field and select a role from the list.
5. Assign a sync key to a unique field, such as Email.
6. Click UPDATE.

Standard Quip to Oomnitza mappings

The following Quip fields can be mapped to Oomnitza:

• Connector Sync Time
• Email
• Id

Launching the integration

Your integration is in Draft mode until the required mandatory fields are added. When added, click Launch to activate your integration. 

If you selected Cloud as the installation type when creating the integration, see Running an extended integration

If you selected Local as the installation type when creating the integration, see Running an extended integration locally.

Viewing data ingested by Oomnitza

Viewing ingested asset data

For asset integrations, click Hardware. If the asset integration also ingests software data, click Software.

Viewing ingested user data

For user integrations, click People. If you chose the option to ingest User and SaaS user data, click Software > SaaS, click the SaaS app, and then click the Users tab. 

Related Links

• Running an extended integration
• Troubleshooting integrations
• Mapping extended integrations

Creating workflows

To automate complex and repetitive tasks, you can create user workflows.

Learn more: Using the API block.

When you select a preset, you must enter the following information in the Configure section:

1. Your Quip credentials.
2. Your Quip API URL. .

To complete actions in QUIP, you can use the following presets:

• Create Folder
• Load User Details
• Add User to Folder
• Remove User from Folder

Quip Create Folder

The Quip Create Folder preset creates a new folder in Quip. To add the preset to a workflow, you must enter the Title of the folder. You can use the Advanced Mode to configure the message payload.

To do this, complete the following steps:

1. In the API block tab, click Advanced Mode.
2. In the Body tab, you can modify the title you added or enter additional values, such as the {{color}}or the {{member_ids}}of the folder. See Quip API documentation: Create a folder.
3. Select the RESPONSE tab. To map the entire response enter {{response}} in the Response field and map it to a custom long text Oomnitza field, such as API Response. When you have the response, you can map individual JSON values to the custom fields as shown in the screen capture.
4. 

Quip Load User Details

The Quip Load User Details loads the details of a Quip user.

Tip
You can get a user ID by running the Quip Create Folder preset. Alternatively, you can get a list of all Quip User IDs when you run the user integration. 

When you select the preset, you must provide a user ID. The Quip User ID is stored in the Advanced Mode.

1. Click Advanced Mode.
2. Select the INFORMATION tab. The Quip user ID is assumed to be stored in the field {{quip_user_id}}. If this is not the case, you can replace the field name in the URL field or enter the user ID directly.
3. Select the RESPONSE tab. To map the entire response enter {{response}} in the Response field and map it to a custom long text Oomnitza field, such as API Response. When you have the response, you can map individual JSON values to the custom fields as shown in the screen capture.
   

See Quip API documentation: Get User.

Quip Add User To Folder

The Quip Add User To Folder preset adds a user to a Quip folder. When you create the workflow, you must provide the Quip Folder ID and Quip User ID.

Tip
You can get the folder ID by running the Quip Create Folder preset. You can call this field directly in the API block by entering {{quip_folder_id}} in the Folder ID field. You can get the Quip User ID by running the user integration or the Quip Create Folder preset. You can call this field directly in the API block by entering {{quip_user_id}} in the User ID field.

You can use the Advanced Mode to configure the message response. To do this, complete the following steps:

1. In the API block tab, click Advanced Mode.
2. 1. Select the RESPONSE tab. To map the entire response enter {{response}} in the Response field and map it to a custom long text Oomnitza field, such as API Response. When you have the response, you can map individual JSON values to the custom fields as shown in the screen capture.
   

See Quip API documentation: Add People to a Folder.

Quip Remove User

The Quip Remove User From Folder preset removes a user from a Quip folder. When creating the workflow, you must provide the Folder ID and the ID of the user you want to add.

You can use the Advanced Mode to configure the message response. To do this, complete the following steps:

1. 1. In the API block tab, click the Advanced Mode button located in the upper right of the window.
   2. In the RESPONSE tab, you can map the entire response by placing {{response}} in the Response field and mapping it to a custom Oomnitza long text field. Then you can map individual JSON values to custom fields, as shown in the screen capture for the Quip Add User TO Folder preset.

See Quip API documentation: Remove people from a folder.

Retrieving SaaS user information and deactivating SaaS users

Retrieving SaaS user roles and last activity timestamps is essential for managing SaaS applications, calculating SaaS costs, and tracking SaaS usage. 

To maintain data hygiene use the deactivate feature to deactivate SaaS users in Oomnitza who are not included in the list of SaaS users when the SaaS application syncs with Oomnitza.

Note
Run the workflow after you run the integration.

To run the workflow, complete these steps:

1. Click Configuration.
2. Click Workflows.
3. Click Add and select Software SaaS Users as the object.
4. Click Blocks and drag and drop the SaaS User Role Retrieval block from the Integration section onto the canvas.
5. Edit the block and select the SaaS.

Creating SaaS user workflows

Reference articles for workflows

• Mapping positive and negative responses
• Troubleshooting workflows 
• Using the API block

Related articles

 Getting started for more information.