Discovering Work

An agent can receive various requests which require a human response by the agent's owner. These requests consist of the following types of inbound work which can be received by an agent:

Type Description
Inbound Connection Offer Someone wants to establish a relationship with you.
Inbound Credential Request You are an issuer and a holder (i.e. end user) wants you to issue a credential to them.
Inbound Credential Offer You are a holder (i.e. end user) and someone is offering a credential to you.
Inbound Verification Request You are a verifier and a prover (i.e. end user) wants you to verify a proof.
Inbound Proof Request You are a prover (i.e. end user) and a verifier wants you to prove something.

The agent's owner can either approve or reject each of these types of inbound work.

Retrieving Inbound Work

The following returns all of the 5 types of inbound work for an agent. In other words, it returns everything that may require human review and response which is associated with the agent.

$ curl -u user1:user1pw $URL/api/v1/waiters
{
  "connections": {
    "offers": {
      "count": 0,
      "items": []
    }
  },
  "credentials": {
    "offers": {
      "count": 0,
      "items": []
    },
    "requests": {
      "count": 0,
      "items": []
    }
  },
  "verifications": {
    "proof_requests": {
      "count": 0,
      "items": []
    },
    "verifications_requests": {
      "count": 0,
      "items": []
    }
  }
}

The value of each item returned is the same as that returned when listing a connection, credential, or verification, respectively.

Inbound Work Notification

Instead of polling the /api/v1/waiters endpoint, you can also register one or more listeners to be notified.

Notifying a web application

To add a REST listener which is listening at the https://myhost/notifications endpoint:

curl -u issuer1:issuer1pw -X POST -d '{"rest": {"url": "https://myhost/notifications"}}' $URL/api/v1/listeners -H 'Content-Type: application/json'

The body of the POST which will then be sent to the REST endpoint for various notifications is of the following form:

{
  'type': '<connections> | <credentials> | <verifications> | <messages>',
  'id': '<id>',
  'state': '<state>',
  'message': '<concise message>',
  'timestamp': <time-of-event>,
  'object': {
    <the complete object>
  }
}

where:

  • type specifies the type of object related to the notification (connections, credentials, verifications, or messages),
  • id is the unique identitier of the object,
  • state is the new state of the object,
  • message is a concise one-line message describing the event,
  • timestamp is the time of the event in milliseconds, and
  • object contains the value of the object (including 'id' and 'state').
Notifying a mobile application

Configure your favorite push notification server to work with a listener.

Alternately, you can use the IBM Cloud Push Notification Service.

Viewing listeners

To list all listeners:

curl -u issuer1:issuer1pw $URL/api/v1/listeners

To list a specific listener where <listener-id> is the id field of the listener as returned by the previous call.

curl -u issuer1:issuer1pw $URL/api/v1/listeners/<listener-id>

Deleting listeners

To delete a listener where <listener-id> is the id field of the listener to be deleted:

curl -u issuer1:issuer1pw -X DELETE $URL/api/v1/listeners/<listener-id>

Finally, last but not least, let's end the tutorial with some troubleshooting tips.