At Your Service! Using Common BlackBerry Dynamics Shared Services

BlackBerry Dynamics (BD) apps can communicate with each other using the Shared Services Framework, a collaboration system that is defined by two components: one that provides a service and another that consumes the service.

You can use this to communicate between two of your own BD apps; however it’s more common to use the capability to integrate with other BD apps. For example, you could use shared services to pass a PDF to a printing application, or to create a draft email message. Both BlackBerry and our development community have defined services for common tasks. This means all BD apps can perform common actions – such as sharing a file or opening a URL – using the same service. Services can be scoped to be public and available for any application to use, or they can be private and internal to an organization. All public Shared Services are listed on the BlackBerry Marketplace Service Listing. Each service also shows the applications that are providers of it.

Your application could implement either side of the service. It could be the consumer and send data to another application or it could be the provider and receive data from another application. Today we’re going to look at how to consume a service. Let’s use the Send Email Service to create an email.

The sample code shown in this article was taken from our Android SharedServicesTestApp and iOS BEMS-SharedServices samples. You can clone and run these sample to follow along. The Android sample demonstrates how to consume the following services:

· Transfer File Service

· Edit File Service

· Send Email Service

· Create Calendar Item Service

· Open HTTP URL Service

· Open UEM App Catalog Service

The iOS sample demonstrates how to consume the following services:

· Transfer File Service

· Send Email Service

· Search directory Service

Step 1 – Finding a Service Provider

The first step is to determine which applications are installed on the device that are providers for the service we want to use, in this case the Send Email Service. In order to query a service, we need to know its service ID and version. Both of those can be found in the service’s listing on the BlackBerry Marketplace. For the Send Email Service, those are:

Service ID: com.good.gfeservice.send-email

Service Version: 1.0.0.0

With this information, we can query to determine what – if any – applications active on this device provide this service. If no providers are found, we can warn the user or disable this feature in our app. Query for service providers like this:

Android



Vector appDetails = GDAndroid.getInstance().getServiceProvidersFor(
        "com.good.gfeservice.send-email",
        "1.0.0.0",
        GDServiceType.GD_SERVICE_TYPE_APPLICATION);

iOS



NSMutableArray *arrayGDServiceProvider = [[[GDiOS sharedInstance] getServiceProvidersFor:kSendEmailServiceName
                                                                                  andVersion:kSendEmailServiceVersion
                                                                              andServiceType:GDServiceTypeApplication] mutableCopy];

This returns 0 to many GDServiceProviders.

Step 2 – Choosing a Service Provider

Now that we have a list of providers, we have a choice to make. If only one provider was returned, the choice of which one to use might be easy. But you may have a specific use case where you need to always use the same application, such as using BlackBerry Access to open a HTTP URL. You could hard code your application to only use a specific application as the provider based on the application’s package name. In most cases, it makes sense to allow the user to choose the provider they wish to use. The GDServiceProvider class provides the application name, application icon and package name of each provider application.

Take a look at the showChoicesAlert method in the SharedServicesTestApp for sample code to build a dialog to show this information to the user.

Step 3 – Call the Service

At this point the user has chosen an application to use as the service provider. The final step is calling the service. This involves creating some JSON that is passed to the GDServiceClient.sendTo method. The JSON parameters are unique for each service. You can check the JSON definition for the send email service in the BlackBerry Marketplace Service Listing for the send email service.

Create the JSON and other parameters and call the send email service like this:

Android



try
{
    Map params = new HashMap<>();

    List recipients =  new ArrayList<>(1);
    recipients.add("someone@blackberry.com");
    params.put("to", recipients);

    params.put("subject", "Send Email Service");

    params.put("body",
    "This email was created using the BlackBerry Dynamics Send Email Service");

    //Add attachments
    File file = new File(WORD_DOC_FILE_NAME);
    String[] attachments = {file.getAbsolutePath()};

    GDServiceClient.sendTo(serviceAddress,
            SEND_EMAIL_SERVICE,
            SEND_EMAIL_SERVICE_VERSION,
            "sendEmail",
            params,
            attachments,
            GDICCForegroundOptions.PreferPeerInForeground);


} catch (final GDServiceException gdServiceException)
{
    TextView output = findViewById(R.id.outputTextView);
    output.setText("AppKineticsModel.sendFiles: unable to transfer file: "
            + gdServiceException.toString());

iOS



NSArray* arr = [[GDiOS sharedInstance] getServiceProvidersFor:sendEmailIdentifier andVersion:sendEmailVersion andServiceType:GDServiceTypeApplication];
    
    bool bbWorkPresent = false;
    GDServiceProvider * serP;
    
    for (GDServiceProvider *serviceProvider in arr) {
        if ([serviceProvider.identifier  isEqual: bbWorkIdentifier]) {
            bbWorkPresent = true;
            serP = serviceProvider;
            break;
        }
    }
    
    if (!bbWorkPresent) {
        [self alertWithTitle:@"Alert!" message:@"BlackBerry Work not installed"];
    }
    
    NSError *err = [[NSError alloc] init];
    
    NSMutableDictionary *params = [[NSMutableDictionary alloc] init];
    NSArray *toRecipients = [_toOutlet.text componentsSeparatedByString:@","];
    [params setObject:toRecipients forKey:@"to"];
    [params setObject:_subjectOutlet.text forKey:@"subject"];
    [params setObject:_messageOutlet.text forKey:@"body"];
    
    [GDServiceClient sendTo:[serP address] withService:@"com.good.gfeservice.send-email" withVersion:@"1.0.0.0" withMethod:@"sendEmail" withParams:params withAttachments:nil bringServiceToFront:GDEPreferPeerInForeground requestID:nil error:&err];

One important thing to note about the sample above, is that the file specified as the attachment must be stored in the BlackBerry Dynamics Secure File System. This is true for all services that pass files, such as the transfer file service and edit file service.

At this point, the user should have an email open and ready to send from an application such as BlackBerry Work. Be sure to check out the full Android SharedServicesTestApp and iOS BEMS-SharedServices samples to see how other services can be used.

About Mark Sohm

Senior Technical Solutions Manager on the Solution Architects team.

Mark Sohm joined BlackBerry in 2003 and currently works as a Senior Technical Solutions Manager on the Solutions Architects team. Mark Sohm has been helping developers create applications using BlackBerry technologies for over 15 years, starting way back with the very first BlackBerry JDK on BlackBerry OS 3.6 through to BlackBerry 10 and now Android with BlackBerry Dynamics and Android Enterprise.

Back