From 54a1a90083d8cacbf2c61b64a8c531d1eca19255 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Wed, 23 Jan 2019 18:46:13 +0000 Subject: [PATCH] [ADF-3745] Updates for doc review (#4203) --- docs/core/identity-user.service.md | 37 ++++++++++- docs/core/renditions.service.md | 63 ++++++++++++++----- .../edit-task-filter-cloud.component.md | 21 +++---- lib/core/form/services/form.service.ts | 2 +- lib/core/services/renditions.service.ts | 53 ++++++++++++++++ .../services/identity-user.service.ts | 40 ++++++++++-- .../edit-task-filter-cloud.component.ts | 1 + tools/doc/doctool.config.json | 2 + 8 files changed, 185 insertions(+), 34 deletions(-) diff --git a/docs/core/identity-user.service.md b/docs/core/identity-user.service.md index 3af046711b..909ac9e1dc 100644 --- a/docs/core/identity-user.service.md +++ b/docs/core/identity-user.service.md @@ -2,7 +2,7 @@ Title: Identity user service Added: v3.0.0 Status: Active -Last reviewed: 2019-01-09 +Last reviewed: 2019-01-23 --- # [Identity user service](../../lib/core/userinfo/services/identity-user.service.ts "Defined in identity-user.service.ts") @@ -13,6 +13,41 @@ Gets OAuth2 personal details and roles for users. ### Methods +- **checkUserHasAnyApplicationRole**(userId: `string`, applicationName: `string`, roleNames: `string[]`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Checks if a user has any application role. + - _userId:_ `string` - ID of the target user + - _applicationName:_ `string` - Name of the application + - _roleNames:_ `string[]` - List of role names to check for + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the user has one or more of the roles, false otherwise +- **checkUserHasAnyClientAppRole**(userId: `string`, clientId: `string`, roleNames: `string[]`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Checks whether a user has any of the client app roles. + - _userId:_ `string` - ID of the target user + - _clientId:_ `string` - ID of the client app + - _roleNames:_ `string[]` - List of role names to check for + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the user has one or more of the roles, false otherwise +- **checkUserHasApplicationAccess**(userId: `string`, applicationName: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Checks if a user has access to an application. + - _userId:_ `string` - ID of the user + - _applicationName:_ `string` - Name of the application + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the user has access, false otherwise +- **checkUserHasClientApp**(userId: `string`, clientId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Checks whether user has access to a client app. + - _userId:_ `string` - ID of the target user + - _clientId:_ `string` - ID of the client app + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the user has access, false otherwise +- **findUsersByName**(search: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Find users based on search input. + - _search:_ `string` - Search query string + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - List of users +- **getClientIdByApplicationName**(applicationName: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Gets the client ID for an application. + - _applicationName:_ `string` - Name of the application + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - Client ID string +- **getClientRoles**(userId: `string`, clientId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Get client roles of a user for a particular client. + - _userId:_ `string` - ID of the target user + - _clientId:_ `string` - ID of the client app + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - List of client roles - **getCurrentUserInfo**(): [`IdentityUserModel`](../../lib/core/userinfo/models/identity-user.model.ts)
Gets the name and other basic details of the current user. - **Returns** [`IdentityUserModel`](../../lib/core/userinfo/models/identity-user.model.ts) - The user's details diff --git a/docs/core/renditions.service.md b/docs/core/renditions.service.md index 839af4f23a..7686ab669a 100644 --- a/docs/core/renditions.service.md +++ b/docs/core/renditions.service.md @@ -2,28 +2,61 @@ Title: Renditions service Added: v2.0.0 Status: Active +Last reviewed: 2019-01-23 --- # [Renditions service](../../lib/core/services/renditions.service.ts "Defined in renditions.service.ts") Manages prearranged conversions of content to different formats. -## Methods +## Class members -`isRenditionAvailable(nodeId: string, encoding: string):`[`Observable`](http://reactivex.io/documentation/observable.html)``
-Has the specified rendition been set up for this item? +### Methods -`isConversionPossible(nodeId: string, encoding: string):`[`Observable`](http://reactivex.io/documentation/observable.html)``
-Is it possible to convert this item to the specified format? - -`getRenditionUrl(nodeId: string, encoding: string): string`
-Gets a URL linking to a rendition. - -`getRenditionsListByNodeId(nodeId: string):`[`Observable`](http://reactivex.io/documentation/observable.html)``
-Gets all available renditions for an item. - -`convert(nodeId: string, encoding: string, pollingInterval: number = 1000)`
-Performs a format conversion on an item directly. +- **convert**(nodeId: `string`, encoding: `string`, pollingInterval: `number` = `1000`, retries: `number` = `5`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Repeatedly attempts to create a rendition, through to success or failure. + - _nodeId:_ `string` - ID of the target node + - _encoding:_ `string` - Name of the rendition encoding + - _pollingInterval:_ `number` - Time interval (in milliseconds) between checks for completion + - _retries:_ `number` - Number of attempts to make before declaring failure + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the rendition was created, false otherwise +- **createRendition**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<__type>`
+ Creates a rendition for a node. + - _nodeId:_ `string` - ID of the target node + - _encoding:_ `string` - Name of the rendition encoding + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<__type>` - Null response to indicate completion +- **generateRenditionForNode**(nodeId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Generates a rendition for a node using the first available encoding. + - _nodeId:_ `string` - ID of the target node + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - Null response to indicate completion +- **getAvailableRenditionForNode**(nodeId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>`
+ Gets the first available rendition found for a node. + - _nodeId:_ `string` - ID of the target node + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>` - Information object for the rendition +- **getRendition**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>`
+ Gets information about a rendition of a node. + - _nodeId:_ `string` - ID of the target node + - _encoding:_ `string` - Name of the rendition encoding + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>` - Information object about the rendition +- **getRenditionUrl**(nodeId: `string`, encoding: `string`): `string`
+ Gets a URL linking to the specified rendition of a node. + - _nodeId:_ `string` - ID of the target node + - _encoding:_ `string` - Name of the rendition encoding + - **Returns** `string` - URL string +- **getRenditionsListByNodeId**(nodeId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionPaging`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md)`>`
+ Gets a list of all renditions for a node. + - _nodeId:_ `string` - ID of the target node + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionPaging`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md)`>` - Paged list of rendition details +- **isConversionPossible**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Checks if the node can be converted using the specified rendition. + - _nodeId:_ `string` - ID of the target node + - _encoding:_ `string` - Name of the rendition encoding + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the node can be converted, false otherwise +- **isRenditionAvailable**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)``
+ Checks if the specified rendition is available for a node. + - _nodeId:_ `string` - ID of the target node + - _encoding:_ `string` - Name of the rendition encoding + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - True if the rendition is available, false otherwise ## Details @@ -42,5 +75,5 @@ in the ADF API. The `encoding` identifies the conversion performed by the rendit See the [Renditions API page](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionsApi.md#createRendition) in the Alfresco JS API for more information about the -[RenditionPaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md) +[`RenditionPaging`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md) class and other implementation details. diff --git a/docs/process-services-cloud/edit-task-filter-cloud.component.md b/docs/process-services-cloud/edit-task-filter-cloud.component.md index 85939c2a35..4696a15005 100644 --- a/docs/process-services-cloud/edit-task-filter-cloud.component.md +++ b/docs/process-services-cloud/edit-task-filter-cloud.component.md @@ -25,23 +25,23 @@ Edits Task Filter Details. | Name | Type | Default value | Description | | ---- | ---- | ------------- | ----------- | | appName | `string` | | (required) Name of the app. | -| id | `string` | "" | (required) The id of the Task filter. | -| filterProperties | `string []` | `['state', 'assignment', 'sort', 'order']` | List of task filter properties to display. | -| toggleFilterActions | `boolean` | `true` | Toggles edit task filter actions. | -| showTitle | `boolean` | `true` | Toggles edit task filter title. | +| filterProperties | `string[]` | | List of task filter properties to display. | +| id | `string` | | (required) ID of the task filter. | +| showTitle | `boolean` | true | Toggles the title. | +| toggleFilterActions | `boolean` | true | Toggles the filter actions. | ### Events | Name | Type | Description | | ---- | ---- | ----------- | | action | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FilterActionType`](../../lib/process-services-cloud/src/lib/task/task-filters/models/filter-cloud.model.ts)`>` | Emitted when a filter action occurs (i.e Save, Save As, Delete). | -| filterChange | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`TaskFilterCloudModel`](../../lib/process-services-cloud/src/lib/task/task-filters/models/filter-cloud.model.ts)`>` | Emitted when a task filter property changes. | +| filterChange | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`TaskFilterCloudModel`](../../lib/process-services-cloud/src/lib/task/task-filters/models/filter-cloud.model.ts)`>` | Emitted when an task filter property changes. | ## Details ### Editing APS2 task filter -Use the application name and task filter id property to edit task filter properties: +Use the `appName` and `id` properties to edit task filter properties: ```html ``` - -All Available properties are: +The available properties are: **_appName_**, **_state_**, **_assignment_**, **_sort_**, **_order_**, **_processDefinitionId_**, **_processInstanceId_**, **_dueAfter_**, **_dueBefore_**, **_claimedDateFrom_**, **_claimedDateTo_**, **_createdDateFrom_**, **_createdDateTo_**, **_taskName_**, **_parentTaskId_**, **_priority_**, **_standAlone_**, **_lastModifiedFrom_**, **_lastModifiedTo_**, **_owner_**, **_dueDateFrom_**, **_dueDateTo_**. diff --git a/lib/core/form/services/form.service.ts b/lib/core/form/services/form.service.ts index 28a5d3d04f..72341fa736 100644 --- a/lib/core/form/services/form.service.ts +++ b/lib/core/form/services/form.service.ts @@ -484,7 +484,7 @@ export class FormService { /** * Gets the ID of a form. - * @param res Object representing a form + * @param form Object representing a form * @returns ID string */ getFormId(form: any): string { diff --git a/lib/core/services/renditions.service.ts b/lib/core/services/renditions.service.ts index 2849a800e9..df29815359 100644 --- a/lib/core/services/renditions.service.ts +++ b/lib/core/services/renditions.service.ts @@ -29,6 +29,11 @@ export class RenditionsService { constructor(private apiService: AlfrescoApiService) { } + /** + * Gets the first available rendition found for a node. + * @param nodeId ID of the target node + * @returns Information object for the rendition + */ getAvailableRenditionForNode(nodeId: string): Observable { return from(this.apiService.renditionsApi.getRenditions(nodeId)).pipe( map((availableRenditions: RenditionPaging) => { @@ -39,6 +44,11 @@ export class RenditionsService { })); } + /** + * Generates a rendition for a node using the first available encoding. + * @param nodeId ID of the target node + * @returns Null response to indicate completion + */ generateRenditionForNode(nodeId: string): Observable { return this.getAvailableRenditionForNode(nodeId).pipe( map((rendition: RenditionEntry) => { @@ -51,6 +61,12 @@ export class RenditionsService { ); } + /** + * Checks if the specified rendition is available for a node. + * @param nodeId ID of the target node + * @param encoding Name of the rendition encoding + * @returns True if the rendition is available, false otherwise + */ isRenditionAvailable(nodeId: string, encoding: string): Observable { return new Observable((observer) => { this.getRendition(nodeId, encoding).subscribe( @@ -70,6 +86,12 @@ export class RenditionsService { }); } + /** + * Checks if the node can be converted using the specified rendition. + * @param nodeId ID of the target node + * @param encoding Name of the rendition encoding + * @returns True if the node can be converted, false otherwise + */ isConversionPossible(nodeId: string, encoding: string): Observable { return new Observable((observer) => { this.getRendition(nodeId, encoding).subscribe( @@ -85,22 +107,53 @@ export class RenditionsService { }); } + /** + * Gets a URL linking to the specified rendition of a node. + * @param nodeId ID of the target node + * @param encoding Name of the rendition encoding + * @returns URL string + */ getRenditionUrl(nodeId: string, encoding: string): string { return this.apiService.contentApi.getRenditionUrl(nodeId, encoding); } + /** + * Gets information about a rendition of a node. + * @param nodeId ID of the target node + * @param encoding Name of the rendition encoding + * @returns Information object about the rendition + */ getRendition(nodeId: string, encoding: string): Observable { return from(this.apiService.renditionsApi.getRendition(nodeId, encoding)); } + /** + * Gets a list of all renditions for a node. + * @param nodeId ID of the target node + * @returns Paged list of rendition details + */ getRenditionsListByNodeId(nodeId: string): Observable { return from(this.apiService.renditionsApi.getRenditions(nodeId)); } + /** + * Creates a rendition for a node. + * @param nodeId ID of the target node + * @param encoding Name of the rendition encoding + * @returns Null response to indicate completion + */ createRendition(nodeId: string, encoding: string): Observable<{}> { return from(this.apiService.renditionsApi.createRendition(nodeId, { id: encoding })); } + /** + * Repeatedly attempts to create a rendition, through to success or failure. + * @param nodeId ID of the target node + * @param encoding Name of the rendition encoding + * @param pollingInterval Time interval (in milliseconds) between checks for completion + * @param retries Number of attempts to make before declaring failure + * @returns True if the rendition was created, false otherwise + */ convert(nodeId: string, encoding: string, pollingInterval: number = 1000, retries: number = 5) { return this.createRendition(nodeId, encoding) .pipe( diff --git a/lib/core/userinfo/services/identity-user.service.ts b/lib/core/userinfo/services/identity-user.service.ts index 954482d890..fa59c560f0 100644 --- a/lib/core/userinfo/services/identity-user.service.ts +++ b/lib/core/userinfo/services/identity-user.service.ts @@ -44,6 +44,7 @@ export class IdentityUserService { /** * Gets the name and other basic details of the current user. + * @returns The user's details */ getCurrentUserInfo(): IdentityUserModel { const familyName = this.getValueFromToken(IdentityUserService.FAMILY_NAME); @@ -56,6 +57,8 @@ export class IdentityUserService { /** * Gets a named value from the user access token. + * @param key Key name of the field to retrieve + * @returns Value from the token */ getValueFromToken(key: string): T { let value; @@ -69,6 +72,8 @@ export class IdentityUserService { /** * Find users based on search input. + * @param search Search query string + * @returns List of users */ findUsersByName(search: string): Observable { if (search === '') { @@ -87,6 +92,9 @@ export class IdentityUserService { /** * Get client roles of a user for a particular client. + * @param userId ID of the target user + * @param clientId ID of the client app + * @returns List of client roles */ getClientRoles(userId: string, clientId: string): Observable { const url = this.buildUserClientRoleMapping(userId, clientId); @@ -102,6 +110,9 @@ export class IdentityUserService { /** * Checks whether user has access to a client app. + * @param userId ID of the target user + * @param clientId ID of the client app + * @returns True if the user has access, false otherwise */ checkUserHasClientApp(userId: string, clientId: string): Observable { return this.getClientRoles(userId, clientId).pipe( @@ -115,7 +126,11 @@ export class IdentityUserService { } /** - * Checks whether user has any of client app role. + * Checks whether a user has any of the client app roles. + * @param userId ID of the target user + * @param clientId ID of the client app + * @param roleNames List of role names to check for + * @returns True if the user has one or more of the roles, false otherwise */ checkUserHasAnyClientAppRole(userId: string, clientId: string, roleNames: string[]): Observable { return this.getClientRoles(userId, clientId).pipe( @@ -139,7 +154,9 @@ export class IdentityUserService { } /** - * Get client id for an application. + * Gets the client ID for an application. + * @param applicationName Name of the application + * @returns Client ID string */ getClientIdByApplicationName(applicationName: string): Observable { const url = this.buildGetClientsUrl(); @@ -158,10 +175,10 @@ export class IdentityUserService { } /** - * Checks a user has access to an application - * @param userId Id of the user + * Checks if a user has access to an application. + * @param userId ID of the user * @param applicationName Name of the application - * @returns Boolean + * @returns True if the user has access, false otherwise */ checkUserHasApplicationAccess(userId: string, applicationName: string): Observable { return this.getClientIdByApplicationName(applicationName).pipe( @@ -172,7 +189,11 @@ export class IdentityUserService { } /** - * Checks a user has any application role + * Checks if a user has any application role. + * @param userId ID of the target user + * @param applicationName Name of the application + * @param roleNames List of role names to check for + * @returns True if the user has one or more of the roles, false otherwise */ checkUserHasAnyApplicationRole(userId: string, applicationName: string, roleNames: string[]): Observable { return this.getClientIdByApplicationName(applicationName).pipe( @@ -184,6 +205,7 @@ export class IdentityUserService { /** * Gets details for all users. + * @returns Array of user info objects */ getUsers(): Observable { const url = this.buildUserUrl(); @@ -203,6 +225,8 @@ export class IdentityUserService { /** * Gets a list of roles for a user. + * @param userId ID of the user + * @returns Array of role info objects */ getUserRoles(userId: string): Observable { const url = this.buildRolesUrl(userId); @@ -222,6 +246,8 @@ export class IdentityUserService { /** * Gets an array of users (including the current user) who have any of the roles in the supplied list. + * @param roleNames List of role names to look for + * @returns Array of user info objects */ async getUsersByRolesWithCurrentUser(roleNames: string[]): Promise { const filteredUsers: IdentityUserModel[] = []; @@ -241,6 +267,8 @@ export class IdentityUserService { /** * Gets an array of users (not including the current user) who have any of the roles in the supplied list. + * @param roleNames List of role names to look for + * @returns Array of user info objects */ async getUsersByRolesWithoutCurrentUser(roleNames: string[]): Promise { const filteredUsers: IdentityUserModel[] = []; diff --git a/lib/process-services-cloud/src/lib/task/task-filters/components/edit-task-filter-cloud.component.ts b/lib/process-services-cloud/src/lib/task/task-filters/components/edit-task-filter-cloud.component.ts index 0ff7399e0d..1307104a94 100644 --- a/lib/process-services-cloud/src/lib/task/task-filters/components/edit-task-filter-cloud.component.ts +++ b/lib/process-services-cloud/src/lib/task/task-filters/components/edit-task-filter-cloud.component.ts @@ -51,6 +51,7 @@ export class EditTaskFilterCloudComponent implements OnChanges { @Input() id: string; + /** List of task filter properties to display. */ @Input() filterProperties: string[] = EditTaskFilterCloudComponent.DEFAULT_TASK_FILTER_PROPERTIES; // default ['state', 'assignment', 'sort', 'order'] diff --git a/tools/doc/doctool.config.json b/tools/doc/doctool.config.json index cb107cbd07..e17de082bb 100644 --- a/tools/doc/doctool.config.json +++ b/tools/doc/doctool.config.json @@ -48,6 +48,8 @@ "NodeEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md", "ProcessInstanceFilterRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/alfresco-activiti-rest-api/docs/ProcessInstanceFilterRepresentation.md", "RelatedContentRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-activiti-rest-api/docs/RelatedContentRepresentation.md", + "RenditionEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md", + "RenditionPaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md", "SiteEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SiteEntry.md", "SitePaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md", "TagEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/TagEntry.md",