@impartner/angular-sdk

This package contains Angular services and typings to facilitate development and integration of Angular web components written for Impartner host applications.

Getting Started

1. Add the @impartner/angular-sdk dependency from npm.

2. Update the application project's environment.ts and environment.prod.ts files to include the impartnerEndpointUrl property.

   • In environment.ts, set this property value to "/api", or some other unique path segment that will be used in the same project's local-serve proxy configuration to proxy requests to the Impartner PRM.
   • In environment.prod.ts, set this property value to an empty string, as it will not be used in production builds.

3. Import ImpartnerSdkModule to the application's root NgModule using the ImpartnerSdkModule.forRoot(...) static function, passing the project's environment constant as the only argument.

   import { ImpartnerSdkModule } from '@impartner/angular-sdk';
   
   @NgModule({
     ...
     imports: [
       ...
       ImpartnerSdkModule.forRoot(environment),
       ...
     ],
     ...
   })
   export class AppModule { ... }

Available Services

This package provides several discrete services to enable integration with Impartner's front-end client applications, and does so through normal Angular dependency injection.

• ImpartnerConfigService
• ImpartnerEventBusService
• ImpartnerMetadataService
• ImpartnerObjectService
• ImpartnerUserService
• IImpartnerHttpClient
• IImpartnerRouter
• IImpartnerLogger

ImpartnerConfigService

Service Type	DI Token	Provided In
ImpartnerConfigService	ImpartnerConfigService	root

A simple service for synchronously fetching current configuration and context information that may be pertinent to client widget or micro front-end.

Methods

Name
getConfig	getConfig() => IImpartnerConfig Returns current configuration and context for the client application, including rendered locale, available locales, available features, and tenant ID.

ImpartnerEventBusService

Service Type	DI Token	Provided In
ImpartnerEventBusService	ImpartnerEventBusService	root

A service for emitting and listening to events available to the Impartner client application and any other widgets or micro front-ends in scope.

Methods

Name
emit	emit<T>(eventName: string, event: T) => void Synchronously emits a new bus event for eventName with the provided payload event of generic type T.
event$	event$<T>(eventName: string) => Observable<T> Returns a hot Observable for bus events with name eventName.

ImpartnerMetadataService

Service Type	DI Token	Provided In
ImpartnerMetadataService	ImpartnerMetadataService	root

A service for fetching metadata about Impartner PRM objects and/or their fields from the host.

Methods

Name
describeAllObjects	describeAllObjects(profile?: DescribeProfile, context?: DescribeContextTypes) => Observable<IPrmObjectDefinition[]> Asynchronously fetches object metadata for all Impartner PRM objects visible to the user type specified by profile, or for the current user if unspecified. The context parameter determines how much information is provided, All and Sync options return basic information (eg. display name, API name, CRUD capabilities), Extended returns in-depth object metadata in the form of the ExtendedObjectProperties interface.
describeObject	describeObject(prmObjectName: string, profile?: DescribeProfile) => Observable<IPrmObjectDefinition | null> Asynchronously fetches basic object metadata for Impartner PRM object prmObjectName for user type specified by profile, or for the current user if unspecified. Result may be null if the named Impartner PRM object does not exist or if it is inaccessible to the user type.
describeFields	describeFields(prmObjectName: string, profile?: DescribeProfile, context?: DescribeContextTypes, depth?: number) => Observable<IPrmFieldDefinition[]> Asynchronously fetches field metadata for all fields of Impartner PRM object prmObjectName for user type specified by profile, or for the current user if unspecified. The context parameter determines how much information is provided, All and Sync options return basic information, Extended returns in-depth field metadata in the form of the ExtendedFieldProperties interface. The depth parameter will recursively populate the foreignFieldDefinitions array for fields with a fieldType of fk.
describeField	describeField(prmObjectName: string, fieldName: string, profile?: DescribeProfile, context?: DescribeContextTypes, depth?: number) => Observable<IPrmFieldDefinition | null> Asynchronously fetches field metadata for named field fieldName of Impartner PRM object prmObjectName for user type specified by profile, or for the current user if unspecified. The context parameter determines how much information is provided, All and Sync options return basic information, Extended returns in-depth field metadata in the form of the ExtendedFieldProperties interface. The depth parameter will recursively populate the foreignFieldDefinitions array for fields with a fieldType of fk.
describeFilterEvaluators	describeFilterEvaluators() => Observable<IFilterCriteriaTypeDefinitions> Asynchronously fetches the collection of different Impartner PRM object field data types and the filter operator types available for them.

ImpartnerObjectService

Service type	DI Token	Provided In
ImpartnerObjectService	ImpartnerObjectService	root

A service for performing CRUD operations with Impartner PRM object records.

Methods

Name
get	get<T>(objectName: string, id: number | string, fields?: string[]) => Observable<IPrmApiResult<T>> Asynchronously retrieves a record with the provided id of the specified Impartner PRM object type objectName, including any fields named in the fields array.
getMany	getMany<T>(objectName: string, options?: ISearchOptions) => Observable<IPrmApiResult<IEntitySearchResult<T>>> Asynchronously retrieves many records of the specified Impartner PRM object type objectName. Providing an options value allows for specifying additional aspects of the request, including returned record fields, filter criteria, sort order, and skip/take values for pagination.
getManyByCriteria	getManyByCriteria<T>(objectName: string, options: ICriteriaSearchOptions) => Observable<IPrmApiResult<IEntitySearchResult<T>>> Asynchronously retrieves many records of the specified Impartner PRM object type objectName. Providing an options value allows for specifying additional aspects of the request, including returned record fields, filter criteria, sort order, and skip/take values for pagination. While similar in nature to getMany, the expanded typing of the options argument allows for alternative filtering logic and behavior, including integration with custom logic.
update	update<TBody, TResult extends TBody = TBody>(objectName: string, id: number | string, body: TBody, returnFields?: (string | keyof TResult)[]) => Observable<IPrmApiResult<TResult> Asynchronously updates a single record with the provided id of the specified Impartner PRM object type objectName, updating its fields according to the provided values in body. The returned results will include the same fields as those present on body, as well as any additional fields specified by the fields array.
updateMany	updateMany<TResult = unknown>(objectName: string, body: unknown[], returnFields?: (string | keyof TResult)[]) => Observable<IPrmPatchManyResult<TResult>> Asynchronously updates multiple records of the specified Impartner PRM object type objectName, updating their fields according to the partial record values in body. Every record in body must have an id property present. The returned results will include the same fields as those present on their records in body, as well as any additional fields specified by the fields array.
delete	delete(objectName: string, id: number | string) => Observable<IPrmApiResult<{ id: number | string }>> Asynchronously deletes a record with the provided id of the specified Impartner PRM object type objectName. The result will be a plain object with the ID of the deleted record.
export	export(objectName: string, criteria: IExportOptions) => Observable<ExportResult> Asynchronously retrieves a file export of records of the specified Impartner PRM object type objectName according to the file type, headers, filter criteria, and sort order in criteria. Result is an ExportResult instance that can trigger file download in the browser by invoking the ExportResult's startDownload() method.

ImpartnerUserService

Service Type	DI Token	Provided In
ImpartnerUserService	ImpartnerUserService	root

A service for accessing basic information about the current user.

Methods

Name
getUser	getUser() => IProfile Retrieves the current user's profile, including (but not limited to) id, user type, name, and email address.
getUserSegments	getUserSegments() => Observable<IUserSegmentationValues> Asynchronously retrieves segmentation information about the current user.

IImpartnerHttpClient

Service Type	DI Token	Provided In
IImpartnerHttpClient	IMPARTNER_HTTP_CLIENT_TOKEN	ImpartnerSdkModule.forRoot(...)

A service for making HTTP calls to the Impartner PRM host. This service ensures that any additional required information (eg. HTTP headers) are present for calls to Impartner. This service should always be used when attempting to make HTTP-based API calls to the Impartner host.

Methods

Name
get	get<T, U extends IApiResultBase = IApiResult<T>>(url: string, options?: IHttpClientOptions) => Promise<U> Asynchronously makes an HTTP GET call to the Impartner PRM resource path specified by url.
post	post<T, U extends IApiResultBase = IApiResult<T>>(url: string, body: unknown, options?: IHttpClientOptions) => Promise<U> Asynchronously makes an HTTP POST call to the Impartner PRM resource path specified by url, with the body value as its payload.
put	put<T, U extends IApiResultBase = IApiResult<T>>(url: string, body: unknown, options?: IHttpClientOptions) => Promise<U> Asynchronously makes an HTTP PUT call to the Impartner PRM resource path specified by url, with the body value as its payload.
patch	patch<T, U extends IApiResultBase = IApiResult<T>>(url: string, body: unknown, options?: IHttpClientOptions) => Promise<U> Asynchronously makes an HTTP PATCH call to the Impartner PRM resource path specified by url, with the body value as its payload.
delete	delete<T, U extends IApiResultBase = IApiResult<T>>(url: string, body: unknown, options?: IHttpClientOptions) => Promise<U> Asynchronously makes an HTTP DELETE call to the Impartner PRM resource path specified by url.

IImpartnerRouter

Service Type	DI Token	Provided In
IImpartnerRouter	IMPARTNER_ROUTER_TOKEN	ImpartnerSdkModule.forRoot(...)

A service for accessing and modifying navigation state within the host Impartner front-end application.

Methods

Name
navigate	navigate(path: string, navigationParams?: INavigationParams, navigationOptions?: INavigationOptions) => Promise<void> Triggers navigation to the specified path within the Impartner client application.
getState	getState() => IRouterState Returns current route state within the Impartner client application, including page title, path, and present query string parameters.
getContentPageMetadata	getContentPageMetadata() Asynchronously retrieves a list of available page routes for navigation. Only applicable within Impartner Portal host applications.

IImpartnerLogger

Service Type	DI Token	Provided In
IImpartnerLogger	IMPARTNER_LOGGER_TOKEN	ImpartnerSdkModule.forRoot(...)

A service for simple logging behavior.

Methods

All below methods accept one message argument and an open-ended number of additional objects to be logged - the only difference between them is the message severity, which is denoted by the method name itself.

Name
trace	trace(message: string, ...argument: unknown[]) => void
info	info(message: string, ...argument: unknown[]) => void
log	log(message: string, ...argument: unknown[]) => void
debug	debug(message: string, ...argument: unknown[]) => void
warn	warn(message: string, ...argument: unknown[]) => void
error	error(message: string, ...argument: unknown[]) => void

Local Development

All of the above documented services will also work in local development, provided the environment object passed to ImpartnerSdkModule.forRoot(environment) includes the property value production: false. However, there are some notable differences when running locally.

• IImpartnerHttpClient
  • HTTP calls made through IImpartnerHttpClient (including those by ImpartnerMetadataService and ImpartnerObjectService) will go to localhost with a root path matching the impartnerEndpointUrl property of the environment object. In order for these requests to adequately resolve, the Angular application's local development build must be configured to proxy calls on that path to an Impartner environment. For instructions on how to configure the proxy for local development, consult the Angular documentation.
• IImpartnerRouter
  • The navigate method will not trigger any actual navigation, but instead will log the provided arguments to the console and trigger a browser alert notifying that navigation was triggered.
  • The getState method will log a trace message to the console and return an object with the current query string parameters and the below name and path properties:

    {
      name: 'Local Development',
      path: '/'
    }

  • The getContentPageMetadata method will log a trace message to the console and return a resolved Promise with an array of predefined, for-testing-only routes.