Sync API: Common problems

Context of this document: The Flip Sync API for users and channels

 

Working closely with our customers, we have seen common patterns in using the Sync API that lead to hurdles and errors.

To make sending data as easy as possible, we put together five common hurdles or errors our customers face during technical onboarding. This guide will help you save time in these typical problems so you can complete the onboarding process fast (please consider that only the required fields are present in the following JSON examples).

Important to know

  • Since the Sync API works asynchronously for all POST requests you will receive from our server, the response HTTP 202 Accepted (unless an error occurs during the validation of the request URL and of the sent JSON. In this case, the response will be HTTP 400 Bad Request).

    To track asynchronous errors, every API request has a request_context that identifies the request. You can set a value for the request_context or leave it unspecified (in the latter case, a unique random value will be assigned to it).

    To get information about the status of your request, you can give the request_context as a path parameter for the endpoint /api/external/v1/requests/{request_context}. If an error occurs, you can get information about the error by sending a request to the endpoint /api/external/v1/requests/{request_context}/errors.

  • The identifiers of a user are username and external_id. The identifiers of a channel are group_id (internal ID created automatically by the Flip backend) and external_id.

  • The old Flip groups are now called channels. To avoid breaking changes in the API, we still use the word group(s) for all endpoint and parameter names.

 

Password policy errors

Every customer account on Flip has a default password policy:

  • The password must not match the last three passwords of a user, and
  • the password should have a minimum length of 8 characters.

(Our customers can choose the password policy on Flip. Ask the people responsible for your company's “Flip” project about the specific password policy that your colleagues picked.)

The issue

Every time you send a password that does not follow the policy, an error occurs, and the password will not be updated.

Assuming that you have the default password policy:

  • When you send a password that matches the last three passwords of a user, you will get the following error:

    {
        "errors": [
            {
                "error_cause": "Invalid password history: Invalid password: must not be equal to any of last 3 passwords.",
                "error_name": "identity_provider",
                "item": {
                    "user_external_id": "7170346245"
                },
                "reported_at": "2022-21-01T08:05:48.975425Z"
            }
        ],
        "next_cursor": {
            "after": "rO0A.......NKUA==",
            "has_more": false
        }
    }
    
  • When you send a password that does not match the eight characters, you will get the following error:

    {
      "errors": [
        {
          "error_name": "identity_provider",
          "error_cause": "Password policy not met: Invalid password: minimum length 8.",
          "reported_at": "2022-12-01T15:34:29.928182Z",
          "item": {
            "user_external_id": "yxcvasdf"
          }
        }
      ],
      "next_cursor": {
        "after": "rO0A....\\u003d",
        "has_more": false
      }
    }
    

The solution

To solve the problem, we suggest changing the approach regarding the process of assigning a password:

  • Build logic for creating an initial password for the same user and use this logic for all users. This logic can be simple, like setting the password equal to the username (which we don’t recommend), or more complicated, like the employee ID + date of the user's creation/update.
  • Every logic has some advantages and disadvantages. That is why we suggest sending the password only for the user's first log in and setting it as temporary.

 

Create or change users’ and channels’ external_id

Usually, the first users and channels on test and production systems are created manually in the Flip app. The external_id is the identifier of an object that the client sets and uses to do CRUD operations using the Sync API.

The issue

Situations:

  • Since users and channels created in the Flip app don’t have an external_id, you cannot update or delete them using the Sync API unless you assign them one.
  • Sometimes, you may want to change the external_id of a user or a channel.

You can create or update an external_id using the Sync API in both situations.

The solution

Every user has a username, and every channel has an “internal ID”, a UUID automatically set by the Flip backend. Both username and “internal ID” are Flip identifiers for the objects.

You can use both to map the object to an external_id:

  • Use the endpoints /api/external/sync/v3/users or /api/external/v1/sync/groups to get all users or all channels.
  • Identify the user or channel that you want to update or delete and copy in the JSON file the value of the key username (e.g., “test_user”) for users or the value of the key name (e.g., “Test Channel”) and id (e.g., “306d…2d8f”) for the channels.

For users, choose an external_id (e.g., “foo”) and send the following JSON example:

{
  "users": [
    {
      "external_id": "foo",
      "first_name": "Test",
      "last_name": "User",
      "system_role": "USER",
      "tags": [
      ],
      "username": "test_user"
    }
  ]
}

For channels, choose an external_id (e.g., “bar”) and send the following JSON example:

{
  "groups": [
    {
      "external_id": "bar",
      "group_id": "306d...2d8f",
      "name": "Test_Channel"
    }
  ]
}

Now, the user or the channel has the wanted external_id.

 

group_id is ignored if the sent external_id is already associated with another channel

As you can see in the previous chapter, you can map an external_id to a channel sending the group_id.

However, there are some cases in which the sent group_id will be ignored. This happens when you send an external_id that is already associated with a channel name. Our backend understands this as trying to update channel attributes other than the name and the external_id.

The typical use case regards the deletion of channels. To cover the edge case of retrieving data falsely deleted, we use a so-called “soft deletion”. This means that users and channels can be retrieved without losing data (i.e., chat content, channel content, etc.). However, this can cause a channel to be present twice. After the deletion of a channel, a new one with the same name was created manually in the app, and now you want to assign an external_id using the group_id.

The issue

Take a look at this use case:

  1. You create the following channel using the Sync API:

    Name group_id external_id
    News from the Headquarters bfa5f3f1-8813-4900-b6c0-bedeef40e7a3 news_from_the_headquarters
  2. After some tests, you decide to delete it.

  3. Your project manager creates a new channel in the Flip app, “News from the Headquarters”, to share information with all headquarters employees.

    Name group_id
    News from the Headquarters 4148b546-76fb-11ed-a1eb-0242ac120002
  4. Some information is shared in the channel.

  5. You want to add many users to this channel using the Sync API. To achieve that, you need to assign to this channel an external_id. You send the following JSON file to map the channel to an external_id:

    {
      "groups": [
        {
          "external_id": "news_from_the_headquarters",
          "group_id": "4148b546-76fb-11ed-a1eb-0242ac120002",
          "name": "News from the Headquarters"
        }
      ]
    }
    
  6. By doing that, the group_id you sent will be ignored since our backend understands your request as a try to reactivate the deleted channel that already has an external_id. Consequently, you now have two channels with the same name:

    Name group_id external_id
    News from the Headquarters 4148b546-76fb-11ed-a1eb-0242ac120002  
    News from the Headquarters bfa5f3f1-8813-4900-b6c0-bedeef40e7a3 news_from_the_headquarters

The solution

Follow these steps:

  1. Change the external_id of the channel that was retrieved by sending the following JSON file:

    {
      "groups": [
        {
          "external_id": "false_id",
          "group_id": "bfa5f3f1-8813-4900-b6c0-bedeef40e7a3",
          "name": "News from the Headquarters"
        }
      ]
    }
    
  2. Delete the channel:

    {
      "groups": [
        {
          "external_id": "false_id"
        }
      ]
    }
    
  3. Map the channel created in the Flip app with the desired external_id:

    {
      "groups": [
        {
          "external_id": "news_from_the_headquarters",
          "group_id": "4148b546-76fb-11ed-a1eb-0242ac120002",
          "name": "News from the Headquarters"
        }
      ]
    }
    

Now you have the correct channel with the desired external_id.

 

Federated identity '…' is not configured for a tenant

The issue

You want the user to log in using Single Sign On (SSO). To set up the identity provider for the user, you send a POST request to the endpoint /api/external/sync/v3/users with the identity_provider field:

{
  "users": [
    {
      "external_id": "foo",
      "first_name": "Test",
      "last_name": "User",
      "system_role": "USER",
      "tags": [
      ],
      "username": "test_user",
      "login": {
        "identity_provider": {
          "alias": "saml-azure",
          "user_id": "test_user",
          "username": "test_user"
        }
      }
    }
  ]
}

You will get by the endpoint /api/external/v1/requests/{request_context}/errors the following error:

{
  "errors": [
    {
      "error_name": "validation",
      "error_cause": "Federated identity 'saml-azure' is not configured for tenant.",
      "reported_at": "2022-12-18T02:45:51.702973Z",
      "item": {
        "user_external_id": "foo"
      }
    }
  ],
  "next_cursor": {
    "after": "rO0N.......1u003d",
    "has_more": false
  }
}

The solution

The error is caused by the fact that your company account does not have an identity provider called saml-azure set up.

To solve the problem, you need to contact Flip so that an identity provider can be set up for your company account.

 

No channel with the given ID exists

The issue

If you send the following POST request to /api/external/v1/sync/groups with a group_id that does not exist:

{
  "groups": [
    {
      "external_id": "bar",
      "group_id": "0027....fe2d8f", // assume this id is false
      "name": "Test_Channel"
    }
  ]
}

You will get the following error:

{
  "errors": [
    {
      "error_name": "not_found",
      "error_cause": "No group with group ID '0027.......fe2d8f' exists.",
      "reported_at": "2022-12-20T14:47:47.014606Z",
      "item": {
        "group_external_id": "foo"
      }
    }
  ],
  "next_cursor": {
    "after": "rO0A.......\\u003d",
    "has_more": false
  }
}

The solution

There is only a real solution to the problem if you send an existing group_id.

When this error occurs, the client’s intention is usually not to assign an external_id to a channel sending the group_id (see other cases in this article).

Instead, the client wants to create a new channel and supposes a group_id should be set. The group_id is an internal ID set by the Flip backend only, and it is not required to create a channel.

 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.