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 (see Create a Push Source and Create a Security Identity Provider for a Secured Push Source), you could use the Push API as shown below to add a raw text item to your source:

Request

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 **********-****-****-****-************

Payload (see Item Models - DocumentBody)

{
  "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 metadata (for example, author, date, documenttype, etc.) are pushed along with the item. These metadata will be mapped to corresponding fields in the index (see About Push Source Item Metadata).

The data property contains the item body itself (simple, raw text in this instance). Be aware that there are other ways to push the body of an item, depending on your specific needs (see Pushing Item Data).

Finally, the item has a set of permissions (see Simple Permission Model Definition Examples). Specifying a permission model is necessary when adding an item to a secured Push source that doesn’t itself have a global permission model in its configuration. In this particular instance, the permission model implies that the item will be accessible by all security identities that are members of the AlphaTeam group, excluding user bob@example.com.

You must define the security identities this permission model refers to, so that allowed users will be able to access the item in their query results. The following request defines the AlphaTeam group in the security identity provider which has been associated to the secured Push source (see Security Identity Definition Examples - Defining a Basic Group):

Request

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

Payload (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"
    }
  ]
}

As this stands, the group members (that is, alice@example.com, bob@example.com, and david@example.com) wouldn’t be recognized by the provider. The recommended way to fix this is to create an alias relationship between each of those group members and the corresponding user in the Email Security Provider. In addition to allowing your provider to detect those users, doing so will allow those users to access content across many secured enterprise systems (see About the Email Security Provider). The following request defines an alias for user alice@example.com (you would perform similar requests to define aliases for users bob@example.com and david@example.com):

Request

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

Payload (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

If you have completed the previous steps, you can validate the success of your push operations by navigating to the Content Browser of the Coveo Administration Console. If you check the View all content box in the Preferences, the item should appear. You may however have to wait a few minutes for your item push request to be processed (see About the Push API Processing Delay).

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 mysecurityidentityproviderc8d9s8d. In contrast, bob@example.com is denied access in both providers.

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 (see also Manage batches of items in a Push source and Manage Batches of Security Identities).

The Push API Tutorials as a whole can also introduce you to more advanced concepts such as creating complex permission models, using custom mappings, etc.