Push API usage example

This is for:

Developer System Administrator

Assuming that you’ve created a secured Push source, along with a security identity provider for your secured Push source, you can then use the Push API to add a raw text item with access permissions to your source.

This article details the different components of a secured Push source and sample requests to add a secured item and its associated security identities.

Adding a secured item

The following sample request adds a secured item to a secured Push source using the PUT /sources/{sourceId}/documents HTTP request.

Request definition

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mysourceidg3c5d1r2/documents?documentId=file%3A%2F%2Ffolder%2Fmytext.txt HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Request body

{
  "author": "Alice Smith",
  "date": "2017-11-08T12:18:41.666Z",
  "documenttype": "Text",
  "filename": "mytext.txt",
  "language": [
    "English"
  ],
  "permanentid": "sample95829alice84720permanent93829id",
  "sourcetype": "Push",
  "title": "My Text",
  "fileExtension": ".txt",
  "data": "This is a sample text written by Alice Smith.",
  "permissions": [
    {
      "allowAnonymous": false,
      "allowedPermissions": [
        {
          "identity": "AlphaTeam",
          "identityType": "Group"
        }
      ],
      "deniedPermissions": [
        {
          "identity": "bob@example.com",
          "identityType": "User"
        }
      ]
    }
  ]
}

In the above example, several pieces of metadata are pushed along with the item (for example, author, date, and documenttype). This metadata will be mapped to the corresponding fields in the index. For more details about the Push source metadata mapping process, see About Push source item metadata.

The data property contains the item body itself. There are other ways to push the body of an item depending on your specific needs.

Finally, the item has a set of permissions. Specifying a permission model is necessary when adding an item to a secured Push source that doesn’t have a global permission model in its configuration. In this example, the item will be accessible to all security identities that are members of the AlphaTeam group, except for user bob@example.com.

Security identity definition

You must define the security identities that an item permission model refers to, so that allowed users can access an item with access permissions in their query results. The following request defines the AlphaTeam group in the security identity provider associated with the secured Push source.

Request definition

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/mysecurityidentityprovider8d9s8d/permissions HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Request body

See Security Identity Models - IdentityBody.

{
  "identity": {
    "name": "AlphaTeam",
    "type": "GROUP"
  },
  "members": [
    {
      "name": "alice@example.com",
      "type": "USER"
    },
    {
      "name": "bob@example.com",
      "type": "USER"
    },
    {
      "name": "david@example.com",
      "type": "USER"
    }
  ]
}

Security identity to Email Security Provider user mapping

Currently, the group members (that is, alice@example.com, bob@example.com, and david@example.com) are not recognized by the provider. The recommended way to fix this issue is to create an alias relationship between each of those group members and the corresponding user in the Email Security Provider. In addition to enabling your provider to detect those users, this will allow them to access content across many secured enterprise systems. The following request defines an alias for user alice@example.com. You should perform similar requests to define aliases for users bob@example.com and david@example.com.

Request definition

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/mysecurityidentityprovider8d9s8d/mappings HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Request body

See Security Identity Models - MappedIdentityBody.

{
  "Identity": {
    "Name": "alice@example.com",
    "Type": "USER"
    },
    "Mappings": [
      {
        "Name": "alice@example.com",
        "Type": "USER",
        "Provider": "Email Security Provider"
      }
    ]
}

Validating the push operations

After the Push API processing delay, you can validate the success of your push operations by navigating to the Content Browser (platform-ca | platform-eu | platform-au) of the Coveo Administration Console. The item should appear.

Image of the item in the Content Browser | Coveo

You can double-click the item to inspect its properties. In particular, you can validate the security identities. The image below shows that alice@example.com and david@example.com both have access to the item, while bob@example.com doesn’t, as expected. Moreover, you can see that the alias relationships for alice@example.com and david@example.com are functional, the access being granted under Email Security Provider as well as under mysecurityidentityprovider8d9s8d. In contrast, bob@example.com is denied access in both providers.

Permissions of the item in the Content Browser | Coveo

What’s next?

In this example, each item and security identity is pushed individually. However, the Push API also allows you to manage items and security identities in batches. A good way to learn about this feature is to do the third Push API tutorial.

The Push API tutorials can also introduce you to more advanced concepts, such as creating complex permission models and using custom mappings.