Package org.odpi.openmetadata.accessservices.digitalservice.api

Interface DigitalRolesInterface

public interface DigitalRolesInterface

DigitalRolesInterface covers the definition of person roles and their appointments. This is to define the digital service managers and the roles associated with agreement.

Method Summary

Modifier and Type	Method	Description
String	appointPersonRole(String userId, String roleGUID, String profileGUID, Date startDate)	Link a person to a person role.
String	createAgreementRole(String userId, String agreementGUID, AgreementRoleProperties agreementRoleProperties, PersonRoleProperties personRoleProperties)	Create a definition of a new role that is part of an agreement such as a digital subscription.
String	createDigitalServiceManagerRole(String userId, String digitalServiceGUID, PersonRoleProperties properties)	Create a definition of a new role for the manager of a digital service.
List<AgreementRoleAppointee>	getAgreementRoles(String userId, String agreementGUID, int startFrom, int pageSize)	Return all the person roles and their incumbents (if any).
List<PersonRoleAppointee>	getDigitalServiceManagers(String userId, String digitalServiceGUID, int startFrom, int pageSize)	Return all the person roles and their incumbents (if any).
PersonRoleElement	getPersonRoleByGUID(String userId, String personRoleGUID)	Retrieve the properties of a person role using its unique identifier.
List<PersonRoleElement>	getPersonRoleByQualifiedName(String userId, String qualifiedName)	Retrieve the properties of a person role using its unique name.
PersonRoleHistory	getPersonRoleHistoryByGUID(String userId, String personRoleGUID)	Retrieve the appointment history for a person role by unique guid.
List<PersonRoleElement>	getPersonRolesByTitle(String userId, String title, int startFrom, int pageSize)	Retrieve all the person roles for a particular title.
void	relievePersonRole(String userId, String roleGUID, String profileGUID, String appointmentGUID, Date endDate)	Unlink a person from a person role appointment.
void	removePersonRole(String userId, String personRoleGUID)	Delete the person role.
void	updateAgreementRole(String userId, String agreementGUID, String roleGUID, boolean isMergeUpdate, AgreementRoleProperties agreementRoleProperties)	Update the name of the role for a specific agreement.
void	updatePersonRole(String userId, String roleGUID, boolean isMergeUpdate, PersonRoleProperties properties)	Update the properties of a specific person role.

Method Detail

createDigitalServiceManagerRole

String createDigitalServiceManagerRole(String userId,
                                       String digitalServiceGUID,
                                       PersonRoleProperties properties)
                                throws UserNotAuthorizedException,
                                       InvalidParameterException,
                                       PropertyServerException

Create a definition of a new role for the manager of a digital service. The role is anchored to the digital service and will be deleted automatically when the digital service is deleted. It can be managed using the methods below before that. A person can be appointed to ths role using the appointPersonRole method. More general support for creating roles is found in Community Profile OMAS and Governance Program OMAS.

Parameters:

userId - calling user

digitalServiceGUID - unique identifier of the digital service to connect the new role to

properties - role properties

Returns:

unique identifier of new role

Throws:

InvalidParameterException - one of the parameters is invalid

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

createAgreementRole

String createAgreementRole(String userId,
                           String agreementGUID,
                           AgreementRoleProperties agreementRoleProperties,
                           PersonRoleProperties personRoleProperties)
                    throws UserNotAuthorizedException,
                           InvalidParameterException,
                           PropertyServerException

Create a definition of a new role that is part of an agreement such as a digital subscription. These roles are often referred to in the agreement. For example, the agreement may refer to the subscriber, payer, data consumer. The name of such a role is stored in the agreementRoleProperties. The properties of the person role that is created to represent the role is stored in personRoleProperties. A person (or multiple people) can be appointed to the new role using the appointPersonRole method. The new person role created is anchored to the agreement and so it is deleted when the agreement is deleted. It can be managed using the methods below before that. More general support for creating roles is found in Community Profile OMAS and Governance Program OMAS.

Parameters:

userId - calling user

agreementGUID - unique identifier of the agreement

agreementRoleProperties - description of a role found in the agreement text

personRoleProperties - properties to use when creating the role.

Returns:

unique identifier of new role

Throws:

InvalidParameterException - one of the parameters is invalid

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

updatePersonRole

void updatePersonRole(String userId,
                      String roleGUID,
                      boolean isMergeUpdate,
                      PersonRoleProperties properties)
               throws UserNotAuthorizedException,
                      InvalidParameterException,
                      PropertyServerException

Update the properties of a specific person role.

Parameters:

userId - calling user

roleGUID - identifier of the person role to update

isMergeUpdate - are unspecified properties unchanged (true) or replaced with null?

properties - properties to change

Throws:

InvalidParameterException - one of the parameters is invalid

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

updateAgreementRole

void updateAgreementRole(String userId,
                         String agreementGUID,
                         String roleGUID,
                         boolean isMergeUpdate,
                         AgreementRoleProperties agreementRoleProperties)
                  throws UserNotAuthorizedException,
                         InvalidParameterException,
                         PropertyServerException

Update the name of the role for a specific agreement.

Parameters:

userId - calling user

agreementGUID - unique identifier of the agreement

roleGUID - identifier of the person role

isMergeUpdate - are unspecified properties unchanged (true) or replaced with null?

agreementRoleProperties - properties to change

Throws:

InvalidParameterException - one of the parameters is invalid

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

removePersonRole

void removePersonRole(String userId,
                      String personRoleGUID)
               throws InvalidParameterException,
                      UserNotAuthorizedException,
                      PropertyServerException

Delete the person role.

Parameters:

userId - calling user

personRoleGUID - identifier of the person role to delete

Throws:

InvalidParameterException - guid or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getPersonRoleByGUID

PersonRoleElement getPersonRoleByGUID(String userId,
                                      String personRoleGUID)
                               throws UserNotAuthorizedException,
                                      InvalidParameterException,
                                      PropertyServerException

Retrieve the properties of a person role using its unique identifier.

Parameters:

userId - calling user

personRoleGUID - unique identifier

Returns:

properties of the role and any current appointees

Throws:

InvalidParameterException - guid or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getPersonRoleHistoryByGUID

PersonRoleHistory getPersonRoleHistoryByGUID(String userId,
                                             String personRoleGUID)
                                      throws InvalidParameterException,
                                             PropertyServerException,
                                             UserNotAuthorizedException

Retrieve the appointment history for a person role by unique guid.

Parameters:

userId - the name of the calling user.

personRoleGUID - unique identifier (guid) of the person role.

Returns:

person role object

Throws:

InvalidParameterException - guid or userId is null

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.

getPersonRoleByQualifiedName

List<PersonRoleElement> getPersonRoleByQualifiedName(String userId,
                                                     String qualifiedName)
                                              throws UserNotAuthorizedException,
                                                     InvalidParameterException,
                                                     PropertyServerException

Retrieve the properties of a person role using its unique name. The results are returned as a list since it is possible that two roles have the same identifier due to the distributed nature of the open metadata ecosystem. By returning all the search results here it is possible to manage the duplicates through this interface.

Parameters:

userId - calling user

qualifiedName - unique name

Returns:

list of roles retrieved

Throws:

InvalidParameterException - name or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getPersonRolesByTitle

List<PersonRoleElement> getPersonRolesByTitle(String userId,
                                              String title,
                                              int startFrom,
                                              int pageSize)
                                       throws UserNotAuthorizedException,
                                              InvalidParameterException,
                                              PropertyServerException

Retrieve all the person roles for a particular title. The title can include regEx wildcards.

Parameters:

userId - calling user

title - identifier of role

startFrom - where to start from in the list of definitions

pageSize - max number of results to return in one call

Returns:

list of matching roles (null if no matching elements)

Throws:

InvalidParameterException - title or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getDigitalServiceManagers

List<PersonRoleAppointee> getDigitalServiceManagers(String userId,
                                                    String digitalServiceGUID,
                                                    int startFrom,
                                                    int pageSize)
                                             throws InvalidParameterException,
                                                    PropertyServerException,
                                                    UserNotAuthorizedException

Return all the person roles and their incumbents (if any).

Parameters:

userId - the name of the calling user.

digitalServiceGUID - unique identifier of the digital service to connect the new role to

startFrom - where to start from in the list of definitions

pageSize - max number of results to return in one call

Returns:

list of person role objects with details of the people appointed to the roles (if any)

Throws:

InvalidParameterException - the userId is either null or invalid.

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.

getAgreementRoles

List<AgreementRoleAppointee> getAgreementRoles(String userId,
                                               String agreementGUID,
                                               int startFrom,
                                               int pageSize)
                                        throws InvalidParameterException,
                                               PropertyServerException,
                                               UserNotAuthorizedException

Return all the person roles and their incumbents (if any).

Parameters:

userId - the name of the calling user.

agreementGUID - unique identifier of the agreement

startFrom - where to start from in the list of definitions

pageSize - max number of results to return in one call

Returns:

list of person role objects with details of the people appointed to the roles (if any)

Throws:

InvalidParameterException - the userId is either null or invalid.

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.

appointPersonRole

String appointPersonRole(String userId,
                         String roleGUID,
                         String profileGUID,
                         Date startDate)
                  throws InvalidParameterException,
                         PropertyServerException,
                         UserNotAuthorizedException

Link a person to a person role.

Parameters:

userId - the name of the calling user

roleGUID - unique identifier (guid) of the person role

profileGUID - unique identifier for the profile

startDate - the official start date of the appointment - null means effective immediately

Returns:

unique identifier (guid) of the appointment relationship

Throws:

InvalidParameterException - the unique identifier of the person role or profile is either null or invalid

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.

relievePersonRole

void relievePersonRole(String userId,
                       String roleGUID,
                       String profileGUID,
                       String appointmentGUID,
                       Date endDate)
                throws InvalidParameterException,
                       PropertyServerException,
                       UserNotAuthorizedException

Unlink a person from a person role appointment.

Parameters:

userId - the name of the calling user

roleGUID - unique identifier (guid) of the person role

profileGUID - unique identifier for the profile

appointmentGUID - unique identifier (guid) of the appointment relationship created by appointPersonRole - this is returned by appointPersonRole and can be retrieved by the getDigitalServiceManagers or getAgreementRoles depending on the type of role.

endDate - the official end of the appointment - null means effective immediately

Throws:

InvalidParameterException - the profile is not linked to this person role

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.