Returning source references

Source references can provide users with rich information about where the data they see in i2 Analyze records came from. By adding source references to the record data that a service returns, you enable extra functionality in the client, including the ability to associate and view images with your records.

Source references provide up to five pieces of information about the source of an i2 Analyze record:

The type of the source that data in the record came from
The name of the source
A description of the source
The location of the source, which might be a URL
An image of the source, which might also be an image for the record

When you return source reference information from a service, only the name is mandatory. However, you must also state whether users can edit or delete the source references that you add to your records.

To add source references to the record data that your service returns to clients, you must arrange to include a sourceReference object as a peer of the properties object in your response from the acquire endpoint.

In your code that generates responses from the acquire endpoint, add at least the following extra content:

{
  ...
  "properties": {
    ...
  },
  "sourceReference": {
    "source": {
      "name": "source_name"
    }
  },
  ...
}

To give users the best experience, add a type and a description for your source that align with the definitions in the source reference schema for the deployment:

  ...
  "sourceReference": {
    "source": {
      "name": "source_name",
      "type": "source_type",
      "description": "source_description"
    }
  },
  ...

If the data in the external source has associated images, you can arrange for users to see an image for a record when they view it by adding an image field to the source object:
```
    "source": {
      ...
      "image": "image_url"
    }
```
You can similarly include the location of the source in the source reference by adding a location field and setting it to either a URL or a text description.
By default, when users add records from an external data source to a chart, they cannot edit or delete the source references that you add. To change that, add a userModifiable field to the sourceReference object:
```
  ...
  "sourceReference": {
    "source": {
      ...
    },
    "userModifiable": true
  },
  ...
```

Completing these steps in your service code means that source references are present in the records that users retrieve and view. Source references are optional, so you can control whether to include them for all records, or just for records of particular types. Finally, source references have the same features in entity and link records, so you do not need to write different code for those two cases.