Connector Development v5.2 References

Pluggability Support 

The following is an explanation of the API pluggability pattern to be implemented for pluggable components in Identity Broker. Following this pattern ensures pluggable components are accessible via the API and that the Swagger documentation correctly self-documents them. 

The following should be read such that ____ are replaced with Agent or Connector, depending on which component is being written. The hypothetical component is called Something, replace it with a suitable name.

Component API Information

The following is a description of the data structures representing the pluggable component

abstract class ____ApiInformationBase<TExtended> : I____ApiInformation<TExtended>

The DataContract for properties that apply to all types of the pluggable component. A TExtended property is also required. The generic type should be limited to being of type I____ExtendedInformation.  Each property should have the [DataMember], [ApiPropertyDescription] and, if appropriate, [Required] attributes. Note that a limitation of Swagger and how it handles generics dictates that this must be a base class and each type of pluggable component must subclass this class.

Interface I____ExtendedInformation

Interface which describes the type-specific configuration of the pluggable component. The only property on this class is a ____TaskType string which should be set to the internal name of the component (ie: Unify.Connector.CSV).

Pluggable Controller

An abstract controller base which contains API methods relating the plugged component. Must subclass ApiController, but ideally should subclass a base class shared between this and the main controller which contains genericized methods for the desired operations. 

Basic Information Retrieval

In situations where the pluggable controller handles added and retrieval of the components, a API methods on the main controller should be added to retrieve one and all of the basic information relating to the configured components, without the specialised extended information. If the retrieval URN lookup is being used, the basic information should also include a URN to the pluggable controllers retrieval method. 

Route Attribute

An attribute which subclasses PlugInVersionedRouteAttributeBase should be created which does nothing except contain the base controller path for the pluggable component. This value should be passed in the first attribute of each base constructor. 

Retrieval URN Lookup

A lookup dictionary used to translate between pluggable component name and the component specific path element. Can be used to generate lookup URN for the specific retrieval method on basic retrieval calls.

Controller Registration

To the engine being extended, add a method matching the following:

public void AddSomethingController<TController, TApi, TExtended>(Version version, Func<TController> createController) 
  where TController : ApiController
  where TApi : ____ApiInformation<TExtended>, new()
  where TExtended : I____ExtendedInformation<strong>
</strong>

The first thing this method must do is ensure that the TController generic type is a subclass of the correct pluggable controller base class. It should also check and retrieve the route attribute, adding the factory name and path element to the retrieval urn lookup.

The true registration of a controller happens in two parts: factory registration and XML documentation registration. Factory registration is done by creating a RegisteredControllerInformation and calling the RegisterControllerFactory method on the ApiEngine. XML registration is performed by generating the XML documentation and calling the RegisterApiDocumentation method on the ApiEngine.

The XML documentation should be generated in two parts. First, a string format template should be created for the XML. This can be done by copying the XML documentation of the project which contains the pluggable controller base class and removing all members except the ones found on the base class. Template variables should include the value of doc//assembly//name and any reference to the generic configuration (which is probably represented like `0). Also add a template variable after these members which is for other members defined by the plug-in.

The additional member XML can be generated with the PropertyDescriptionAdapter and ControllerMethodDescriptionAdapter classes.

In-built Pluggable Types

Where there are in-built types of pluggable components, each should have ApiInformation and ExtendedInformation classes created. Instead of a pluggable controller, the methods found on the pluggable controller base should be replicated on the main controller.

Using Pluggability

The following is an explanation of the API pluggability pattern to be implemented when creating pluggable components.

Component API Information

A class which subclasses ___ApiInformation<SomethingExtendedInformation> should be created. It does not need to contain any methods or properties.

A class should be created which implements I____ExtendedInformation and has the [DataContract] attribute. The  ___TaskType property should return the internal component name (ie: Unify.Connector.CSV). Any other component specific  properties should be added here with the [DataMember] attribute and [Required] if needed.

Pluggable Controller

A controller class should be created which subclasses ___TaskControllerBase. The controller should have the [___PlugInVersionRoute] attribute.

The base controller will provide the standard API methods for this pluggable component type, however additional API methods can be defined by a class method with the appropriate [Http___] attribute, a [ApiMethodDescription] attribute and a [ApiMethodParamDescription] for each method parameter.

PlugIn

The plugin should call the AddSomethingController method on the extended engine.

API Client Generation

To generate the Web API Client code (to allow communication from the user interface back to the service):

  1. install nSwagStudio
  2. Install or deploy new pluggable API
  3. Start Identity Broker
  4. Create a new Web API endpoint, with a white-list filter including only the new API
  5. Target nSwagStudio at the Identity Broker API endpoint
  6. Set the following options:
    1. Off: Generate exception classes (they're included in the the SDK Framework)
    2. Off: Generate DTO Types (these are the ApiInformation and ExtendedInformation classes from above)
  7. Generate the client and make available to the user interface code

    _SomethingClient = new SomethingClient {BaseUrl = ApiAddress};

Is this article helpful for you?