Relations

A customer relation is a somewhat abstract concept that represents a connection between a customer and some other entity. The other entity could be another customer, a user, or a connection to some external system, such as an SSO. The type of the customer relation is determined by the relation type.

To see concrete examples of scenarios where customer relations are appropriate, see the Examples page. The main alternative to customer relations is dynamic attributes. Here is a checklist that can help determine whether you should use customer relations:

• If you want to connect customers to other customers, or to users in the User Register, use customer relations.

• If you need to include a title in the relation, use customer relations.

• If you need custom validation of the reference key, e.g. that's it a number, a date, etc., use dynamic attributes.

• If the values you want to store are simply data, use dynamic attributes. If the values imply a logical relationship, even if it's an relationship to something in an external database, use customer relations.

Every customer relation belongs to a relation type. Each relation type has a unique code that's used to identify the relation type when adding customer relations. In addition to that, relation types have a reference type and title mode, which determine what validation rules to use when creating customer relations.

Reference Types

Every relation type has a ReferenceType. The reference type determines what kind of entity customers will be connected to when the relation type is used, and therefore determines what kind of reference key validation is performed when a customer relation is created. There are currently four available reference types:

• External

• Customer

• Subscription

• User

When the External reference type is used, no special validation of the reference key is done. The reference is assumed to point to some unique ID in an external database. The only requirements are that some reference key must be present, and that it may not exceed the maximum length of 400 characters.

When the Customer reference type is used, the reference key given to CreateCustomerRelation must be a valid customer number. If the reference given is not a valid customer number, or if isn't even numeric, an InvalidReferenceFault will be thrown.

When the Subscription reference type is used the same rules apply as for the Customer type, but with the additional stipulation that a title code must always be given, and that the customer must have a subscription (active or inactive) for that title. Even if a valid customer number is given, an InvalidReferenceFault will be thrown if the customer does not have a past or present subscription for the title.

Caution

It's currently possible to create a relation type where the reference type is Subscription but where the title mode is not Required, but this should be avoided. If the title mode is Optional it will give the false impression that it's possible to add customer relations for the relation type where no title code is given and no subscription exists, but this is not the case. If the title mode is Forbidden it will actually be impossible to create any customer relations at all for that relation type.

Finally, when the User reference type is used, the reference must be an email address for which there exists a user in the User Register.

Title Modes

Every relation type has a TitleMode, which determines whether a title code must be, may be or must not be given when creating customer relations. There are three possible title modes:

• Required

• Optional

• Forbidden

The title modes should be fairly self-explanatory. When the title mode is Required for some relation type, customer relations added for that relation type must always have a title code. When the title mode is Forbidden, it's an error to give a title code. When the title mode is Optional, a title code may be given or it may be omitted. Whenever a title code is given, it must refer to a valid title.

Note
The reason a fault is thrown when a title code is given for relation types where the title mode is Forbidden, rather than the title code simply being ignored, is that passing a title code in these cases indicates either a logical error or a configuration error, and should be attended to quickly.

To create new customer relations, use the CreateCustomerRelation method. You will need to specify a customer number and a relation type code. In addition to that you must provide a reference key, but the specifics of that value depend on the relation type. The Reference field is always required, and currently has a maximum length of 400 characters.

Depending on the TitleMode of the relation type you may also need to specify a title code. When given, the title code must always refer to a valid title. The TitleCode field may therefore be either required, optional or forbidden. If the relation type says that giving a title code is required but none is given, or if the relation type says that giving a title code is forbidden but one is given anyway, an EntityValidationFault will be thrown.

If you need to store some extra information associated with the customer relation, you can use the AdditionalValue property. The AdditionalValue field is optional. Currently, the maximum length of the AdditionalValue field is 400 characters.

If you want to indicate the source of the customer relation, use the Source field. Examples of sources could for instance be the name of the server from which the relation was added, the name of the user who added it, or simply the name of a piece of software. The Source field is optional, and currently has a maximum length of 100 characters.

There is currently only a single method for retrieving existing customer relations: GetCustomerRelationsByCustomer. This method will return all customer relations for a single customer. If this method does not satisfy your requirements, please contact Infosoft.

In order to delete a customer relation, use the DeleteCustomerRelation method. You will need to provide the unique ID that was assigned to the customer relation when it was created. This ID can be found by retrieving the customer relation using the GetCustomerRelationsByCustomer method.

There's currently no explicit support for updating the values of an existing customer relation. If you need to update a customer relation that already exists, for example because you need to update the reference key or change the AdditionalValue field, you will have to delete the existing customer relation and create a new one. In other words, first call DeleteCustomerRelation and then CreateCustomerRelation.

The methods in the Customer Relation API may throw various SOAP faults. For most of these faults it probably isn't possible (or desirable) for the client to do anything else than to catch the error, show the user an error message, and possibly log the fault somewhere. This is because all the applicable faults indicate either a configuration error on the server or a logical error on the client.

Likely the most common source of faults will be CustomerNotFoundFault and InvalidReferenceFault. CustomerNotFoundFault will happen when CreateCustomerRelation or GetCustomerRelationsByCustomer is called with a customer number that doesn't exist. InvalidReferenceFault will be thrown by CreateCustomerRelation when validation fails on the reference key. For details on the validation rules, refer to the Reference Type section.

CreateCustomerRelation will throw a CustomerRelationAlreadyExistsFault in cases where there already exists an identical relation for the same customer. This means that the relation type, customer, title and reference are all identical to a customer relation that already exists. The AdditionalValue, Source and Audit fields will not be included in the uniqueness check, so it isn't possible to have two different relations with the same reference/relation type/title/customer even though these fields are different.

Reference

Other Resources