Creating an Invite External Users Handler
You can create an Invite External Users Handler for the
Rights Management service. An Invite External Users Handler enables
the Rights Management service to invite external users to become
Rights Management users. After a user becomes a Rights Management
user, the user is able to perform tasks, such as opening a policy-protected
PDF document. After the Invite External Users Handler is deployed
to LiveCycle, you can use Administration Console to interact with
An Invite External Users Handler is a LiveCycle
component. Before you create an Invite External Users Handler, it
is recommended that you become familiar with creating components.
(See Creating Your First Component
Summary of steps
To develop an Invite External Users Handler,
you must perform the following steps:
Set up your
Define the Invite External Users Handler implementation.
Define the component XML file.
Deploy the Invite External Users Handler.
Test the Invite External Users Handler.
This section creates a Java class that corresponds
to the InviteExternalUsersSample.java file that can be located in
the [install directory]\Adobe\Adobe LiveCycle ES4\sdk\samples\RightsManagement\InviteExternalUsers\Java\ folder,
where [install directory] is the LiveCycle installation location.
As you are reading through this section, it is recommended that
you also refer to this JAVA file.
Setting up your development environment
To set up your development environment, you must create
a new Java project, such as an Eclipse project. The version of Eclipse
that is supported is 3.2.1 or later.
Management SPI requires the edc-server-spi.jar file to be set in
your project’s class path. If you do not reference this JAR file,
you cannot use the Rights Management SPI in your Java project. This
JAR file is installed with the LiveCycle SDK in the [install directory]\Adobe\Adobe LiveCycle ES4\sdk\spi folder.
In addition to adding the edc-server-spi.jar file to your project’s
class path, you must also add the JAR files that are required to
use the Rights Management Service API. These files are needed to
use the Rights Management Service API within the Invite External
Defining the invite external users handler implementation
To develop an invite external users handler, you must create
a Java class that implements the com.adobe.edc.server.spi.ersp.InvitedUserProvider interface.
This class contains a method named invitedUser,
which the Rights Management service invokes when email addresses
are submitted using the Add Invited Users page accessible through
Administration Console. (See Testing the invite exernal users handler.)
The invitedUser method accepts a java.util.List instance,
which contains string-typed email addresses that are submitted from
the Add Invited Users page. The invitedUser method
returns an array of InvitedUserProviderResult objects,
which is generally a mapping of email addresses to User objects
(do not return null).
Note: In addition to demonstrating how to create an
invite external users handler, this section also uses the LiveCycle
The implementation of the invite external users handler contains
a user-defined method named createLocalPrincipalAccount.
This method accepts a string value that specifies an email address
as a parameter value. The createLocalPrincipalAccount method
assumes the pre-existence of a local domain called EDC_EXTERNAL_REGISTERED.
You can configure this domain name to be anything you wish; however,
for a production application, you may want to integrate with an
The createUsers method iterates over every email
address and creates a corresponding User object
(a local user in the EDC_EXTERNAL_REGISTERED domain).
Finally, the doEmails method is called. This method
is intentionally left as a stub in the sample. In a production implementation,
it would contain application logic to send invitation email messages
to the newly-created users. It is left in the sample to demonstrate
the application logic flow of a real application.
Defining the invite external users handler implementation
invite external users handler implementation accepts email addresses
that are submitted from the Add Invited Users page accessible through
public class InviteExternalUsersSample implements InvitedUserProvider
private ServiceClientFactory _factory = null;
private User createLocalPrincipalAccount(String email_address) throws Exception
String ret = null;
// Assume the local domain already exists!
String domain = "EDC_EXTERNAL_REGISTERED";
List aliases = new ArrayList();
aliases.add( email_address );
User local_user = UMBaseLibrary.createUser( email_address, domain, email_address );
local_user.setCommonName( email_address );
local_user.setEmail( email_address );
local_user.setEmailAliases( aliases );
// You may wish to disable the local user until, for example, his registration is processed by a confirmation link
//local_user.setDisabled( true );
DirectoryManager directory_manager = new DirectoryManagerServiceClient( _factory );
String ret_oid = directory_manager.createLocalUser( local_user, null );
if( ret_oid == null )
throw new Exception( "FAILED TO CREATE PRINCIPAL FOR EMAIL ADDRESS: " + email_address );
protected User createUsers( List emails ) throws Exception
ArrayList ret_users = new ArrayList();
_factory = ServiceClientFactory.createInstance();
Iterator iter = emails.iterator();
while( iter.hasNext() )
String current_email = (String)iter.next();
ret_users.add( createLocalPrincipalAccount( current_email ) );
return (User)ret_users.toArray( new User );
protected void doInvitations(List emails)
// Here you may choose to send the users who were created an invitation email
// This step is completely optional, depending on your requirements.
public InvitedUserProviderResult invitedUser(List emails)
// This sample demonstrates the workflow for inviting a user via email
User principals = createUsers(emails);
InvitedUserProviderResult result = new InvitedUserProviderResult[principals.length];
for( int i = 0; i < principals.length; i++ )
result[i] = new InvitedUserProviderResult();
result[i].setEmail( (String)emails.get( i ) );
result[i].setUser( principals[i] );
System.out.println( "SUCCESSFULLY INVITED " + result.length + " USERS" );
catch( Exception e )
System.out.println( "FAILED TO INVITE USERS FOR INVITE USERS SAMPLE" );
return new InvitedUserProviderResult;
Note: This Java class is saved as a JAVA
file named InviteExternalUsersSample.java.
Defining the component XML file for the authorization handler
You must define a component XML file in order to deploy
the invite external users handler component. A component XML file
exists for each component and provides metadata about the component.
For more information about the component XML file, see the ComponentXML Reference.
The following component.xml file is used for the invite external
users handler. Notice that the service name is InviteExternalUsersSample and
the operation this service exposes is named invitedUser.
The input parameter is a java.util.List instance
and the output value is an array of com.adobe.edc.server.spi.esrp.InvitedUserProviderResult instances.
Defining the component XML file for the invite external users handler
<auto-deploy category-id="Samples" service-id="InviteExternalUsersSample" major-version="1" minor-version="0"/>
<input-parameter name="input" type="java.util.List" required="true"/>
<output-parameter name="result" type="com.adobe.edc.server.spi.esrp.InvitedUserProviderResult"/>
Packaging the invite external users handler
To deploy the invite external users handler to LiveCycle,
you must package your Java project into a JAR file. You must ensure
that the external JAR files on which the invite external users handler’s
business logic depends, such as the edc-server-spi.jar and adobe-rightsmanagement-client.jar
files are also included in the JAR file. As well, the component
XML file must be present. The component.xml file and external JAR
files must be located at the root of the JAR file.
The following illustration shows the Java project’s content that
is packaged into the invite external users handler’s JAR file.
You must package the invite external users handler into a JAR
file. In the previous diagram, notice that .JAVA files are listed.
Once packaged into a JAR file, the corresponding .CLASS files must
also be specified. Without the .CLASS files, the authorization handler
does not work.
After you package the external authorization
handler into a JAR file, you can deploy the component to LiveCycle.
Only one invite external users handler can be deployed at a given
time. (See Deploying your component
Testing the invite exernal users handler
To test the invite external users handler, you can add
external users to invite by using Administration Console.
To add external users to invite using Administration Console:
Deploy the invite external users handler’s JAR file using
Workbench. (See Deploying your component.)
Restart the application server.
Log in to Administration Console.
Click Services > Rights Management 11 > Configuration > Invited User Registration.
Enable invited user registration by checking the Enable invited user registration box.
Under Use Built-in registration system, click No.
Save your settings.
From the LiveCycle Administration Console home page, click Settings > User Management > Domain Management.
Click New Local Domain. On the following page, create
a domain with the name and identifier value of EDC_EXTERNAL_REGISTERED.
Save your changes.
From the LiveCycle Administration Console home page, click Services > Rights Management 11 > Invited and Local Users.
The Add Invited User page appears.
Enter email addresses (because the current invite external
users handler does not actually send email messages, the email addressed
do not have to be valid). Click OK. The users are invited
to the system.
From the LiveCycle Administration Console home page, click Settings > User Management > Users and Groups.
In the Find field, enter an email address that you
specified. Click Find. The user you invited appears as a
user in the local EDC_EXTERNAL_REGISTERED domain.