Creating Groups and sending Invitations via API

We have had some success with User creation thanks to the previous thread, we now need to know how to do the following:

Creation of a new group via API? We always get 'you do not have permission to create a group' (or words to that effect) even though we used UserManager.Authenticateuser()

How do we send out a manually-created invitation via the API using the group of users created in the previous step?

Any sample code for this would be greatly appreciated.

[ncushing]

Shane,

Based on the error you are seeing, you are calling the correct methods. This is an issue with the 4.2 developer's kit that we have resolved in 4.3. To work around this, you'll need to wait for 4.3 which will be available early next month, or run your code in the context of a web application with session state available.

Currently, when a user is authenticated, a token that identifies the user is stored in the session. This token also links the user to it's Principal, which includes identity, profile, and security information. The user group methods check for a logged-in principal, and if session state is not available no user token will be found, resulting in the error you see.

In 4.3, we changed the methods so that they accept the user principal as an argument rather than trying to look it up in the security cache.

The code below illustrates this.

using Checkbox.Users;
using Prezza.Framework.Security.Principal

ExtendedPrincipal principal = (ExtendedPrincipal)UserManager.AuthenticateUser("AUser", "APassword");

Group newGroup = Group.CreateGroup("A Group", "A Group Description");

newGroup.AddUser("User1");
newGroup.AddUser("User2");
newGroup.AddUser("User3");

//Current API
Group.Commit(newGroup);

//4.3 API
Group.Commit(newGroup, principal);

Due to time constraints we'll need to use the 4.2 method (running in the context of a web application with session state available).

We have used the test code below but we seem to missing something:

ExtendedPrincipal Principal = (ExtendedPrincipal)UserManager.AuthenticateUser("admin", "admin");
// below line is just for testing the UserManager.GetCurrentPrincipal();
// this will return null value like   logincachemanager=null,securitycache=null,sessiontokenprovider=null
IPrincipal IP = UserManager.GetCurrentPrincipal();
// below line is to check the authorization     running successfully not throwing any error.
if (!AuthorizationFactory.GetAuthorizationProvider().Authorize((Principal as ExtendedPrincipal), "Group.Create"))
{
throw new AuthorizationException();
}
// geting error in below line "You have not a permission to do that"
Group newgroup = Group.CreateGroup("AGroup", "A Group Description");
Group.Commit(newgroup);
 
stack trace :
Prezza.Framework.Security.AuthorizationException was unhandled by user code
  Message="You do not have permission to perform this operation."
  Source="Checkbox"
  StackTrace:
       at Checkbox.Users.Group.CreateGroup(String name, String description)

Also, we still need some sample code for sending an existing Invitation. We have determined the following:

There are 5 classes available related to invitation.
Classes Are:

Invitation
Invitationmanager
invitationsender
InvitationTemplate
InvitationRecieve

1. How can we use the method of these classes ?
We need either documentation or some sort of sample code.

2. Invitation INV = new Invitation(1003); where 1003 is the invitation id taking from table name ckbx_invitation

Error: Message = "DataID must be greater than zero."

3 There are Start,Stop,Resume,Dowork method available in Invitationsender class but not find out how can we use these method ?

Invitation INV_V=InvitationManager.GetInvitation(1003);
Stack Trace: 
[AuthorizationException: You do not have permission to perform this operation.]
   Checkbox.Panels.EmailListPanel..ctor() +116

[ncushing]

I just wanted to let you know that I'm working on putting together a sample solution & project to provide you for the invitation and group stuff. It will take me a little bit to get it together but hopefully I should have something for you tomorrow.

-Noah

We are very tight for time so if you can give us whatever sample code you can today that would be most appreciated. It doesn't necesarilty need to be a full solution etc. We just need to understand how we set the "current" principal to have permissions to do admin tasks.

... And also some direction on how to trigger an Invitation to be sent a newly created group.

Regards,
Shane

[ncushing]

Shane,

It took me a while to track down the likely issue with the User Manager. The key is to call UserManager.Initialize() before using the class.

The initialize method creates the internal caches used to store authenticated user information. If these caches are not enabled, a user can authenticate but the authentication state is not persisted.

Since these caches are static members of the class, you only need to call Initialize once per life cycle of the web application. A good way to prevent calling it multiple times is to store an initialized flag, such as setting HttpContext.Current.Application["UMInitialized"] = true.

That should get you over the user manager hump at least. With that out of the way I can get to preparing the invitation information for you.

-Noah

[ncushing]

Shane,

Here is some commented code that illustrates the full process of Authenticating a user, loading a survey, and creating/sending an invitation. Thank you for your patience while I put this together...If you have further questions, please do not hesitate to ask. Due to post size limits, I'll break it up into two posts.

Code Part 1

    using System;
    using System.Data;
    using System.Security.Principal;
    using System.Collections.Generic;
    using System.Collections.ObjectModel;

    using Checkbox.Users;
    using Checkbox.Forms;
    using Checkbox.Panels;
    using Checkbox.Security;
    using Checkbox.Invitations;
    using Checkbox.Messaging.Email;

    /// 

    /// Authenticate a user, load a survey, create an invitation, add panelists
    /// to the invitation, then send the invitation.
    /// 
    private void CreateAndSendInvitation()
    {
        //Initialize the user manager, only needs to be done once per
        // IIS Application lifetime.
        UserManager.Initialize();

        //Authenticate with a user that has sufficient access to send
        // invidations.
        UserManager.AuthenticateUser("admin", "admin");

        //Select a survey to use for the invitation
        // The query will return a data set with information for all
        //  response templates that the logged-in principal has the 
        //  specified permission on.  In this case, the principal
        //  is in the "System Administrator" role so the permission
        //  passed is not used.
        DataSet rtData = ResponseTemplateManager.GetAvailableResponseTemplates("Form.Administer");

        ResponseTemplate surveyToCreateInvitationFor = null;

        if (rtData.Tables.Count > 0)
        {
            DataRow[] rtDataRows = rtData.Tables[0].Select();

            if (rtDataRows.Length > 0)
            {
                surveyToCreateInvitationFor = ResponseTemplateManager.GetResponseTemplate((int)rtDataRows[0]["ResponseTemplateID"]);
            }
        }

        //The survey was successfully loaded, now try to create an invitation
        if (surveyToCreateInvitationFor != null)
        {
            //Create the object
            Invitation invitation = new Invitation();

            //Associate the invitation with the survey
            invitation.SetParentID(surveyToCreateInvitationFor.ID.Value);

            //Customize the invitation template, which is where the body, from address, format
            // etc. are configured
            invitation.Template.Format = MailFormat.Text;
            invitation.Template.FromAddress = "surveyadmin@mycompany.com";
            invitation.Template.FromName = "Survey Administrator";
            invitation.Template.Subject = "An invitation to take a survey.";

            //Set the invitation body to include the URL for the survey.  Replace
            // spaces in the guid to help avoid any url encoding issues.
            // Also, in order to track the invitation responses, we need to add an
            // @@InvitationID parameter.
            invitation.Template.Body = "Please take the this survey: http://www.mycompany.com/survey.aspx?InvitatinID=@@InvitationID&s=" + surveyToCreateInvitationFor.GUID.ToString().Replace("-", "");

            //Save the invitation before we start to add panelists
            invitation.Save();


            //Now, let's add panelists.  An invitation supports types of panelists:
            // Users, Email Addresses, Email Lists, User Groups

            /********************* User Panelist ********************/
            List userPanelistsToAdd = new List();

            IIdentity panelistIdentity = UserManager.GetUserIdentity("inviteeUserName");

            if (panelistIdentity != null)
            {
                userPanelistsToAdd.Add(panelistIdentity);
                invitation.AddPanel(userPanelistsToAdd);
            }

            /********************* Email Address Panelist *************/
            List emailAddressesToAdd = new List();

            emailAddressesToAdd.Add("emailaddress1@mycompany.com");
            emailAddressesToAdd.Add("emailaddress2@mycompany.com");

            invitation.AddPanel(emailAddressesToAdd);

            /********************* Email List Panelist ****************/
            //EmailList panels are managed through the Users->Email Lists
            // section of Checkbox.
            DataSet emailListData = EmailListPanel.GetAvailableEmailLists();

            //Add a random email list
            if (emailListData.Tables.Count > 0)
            {
                DataRow[] emailListDataRows = emailListData.Tables[0].Select();

                if (emailListDataRows.Length > 0)
                {
                    int emailPanelID = (int)emailListDataRows[0]["PanelID"];

                    EmailListPanel panel = PanelManager.GetPanel(emailPanelID) as EmailListPanel;

                    if (panel != null)
                    {
                        invitation.AddPanel(panel);
                    }
                }
            }

            /********************* User Group Panelist ****************/
            //Add a user group panel to the invitation
            //Again, since we are an admin user, the actual permissions don't matter, but
            // if a non-admin user were creating the invitation, the appropriate permission
            // would be "View Group Membership" which is "Group.View"
            Group[] userGroups = Group.GetGroups(PermissionJoin.Any, "Group.View");

            //Pick a random group to add...
            if (userGroups.Length > 0)
            {
                invitation.AddPanel(userGroups[0]);
            }

            //Now that all the panelists have been added, save the invitation.  If it is not
            // saved, errors will result when sending
            invitation.Save();

[ncushing]

Code Part 2

            //Panelists vs. Recipients
            //Conceptually, a Panelist is a potential Recipient, but does not become a Recipient
            // until and invitation has been sent.
            //We can check the list of recipients by calling the GetRecipients(...) method of the 
            //  invitation with a RecipientFilter parameter.  In all cases except "Pending" only
            //  recipients that the software has attempted to send an invitation to will be returned.
            //
            //  The RecipientFilter suports 6 values:
            //  All             -- Get all recipients that have not been deleted and have been
            //                      sent an invitation.
            //  Current         -- Get all recipients thave have not been deleted and have not
            //                      opted out of the invitation.
            //  NotResponded    -- Get all recipients that have not completed the survey.
            //  OptOut          -- Get all recipients that have clicked the opt-out link in the 
            //                      invitation email.
            //  Pending         -- Unlike the other filters, when Pending is specified only recipients
            //                      that the software has NOT attempted to send an email to will
            //                      be returned.
            //  Responded       -- Get all recipients that have responded to the invitation.

            //Get the list of pending recipients, since these are the people we want to invite. To send
            // a reminder message, we could use the list of "NotResponded" recipients.
            ReadOnlyCollection recipients = invitation.GetRecipients(RecipientFilter.Pending);

            //Now let's get to work sending the invitation.
            foreach (Recipient recipient in recipients)
            {
                //Copy the template, which will be "personalized" by the recipient
                InvitationTemplate templateCopy = invitation.Template.Copy();

                //Personalize the template, this includes adding the invitation id, any
                // user profile properties, etc.  Fields in the invitation that can be
                // customized are the body and the subject.  If the recipient is 
                // a registered user, you can make the body or subject contain the value
                // of a profile field by adding a @@[FIELD_NAME] token to the message or subject.
                // For example, to add the user's name and password, you could put something like
                // this in the message:
                // 
                // User Name: @@UserName
                // Password: @@Password
                //
                recipient.PersonalizeTemplate(invitation, templateCopy);

                //Create and send a mail message.
                EmailMessage msg = new EmailMessage();
                msg.To = recipient.EmailToAddress;
                msg.From = templateCopy.FromName + "<" + templateCopy.FromAddress + ">";
                msg.Body = templateCopy.Body;
                msg.Subject = templateCopy.Subject;

                //Send the message, which exception catching so the errors can be reported.
                try
                {
                    //If successful, mark the invitation as successfully sent to this
                    // recipient.
                    EmailGateway.Send(msg);
                    recipient.SuccessfullySent = true;
                }
                catch (Exception ex)
                {
                    //If successful, mark the invitation as not successfully sent to this
                    // recipient and record the error, which will appear in the invitation
                    // management screens in the application.
                    recipient.SuccessfullySent = false;
                    recipient.Error = ex.Message;
                }

                //Store the date/time the attempt was made.
                recipient.LastSent = DateTime.Now;

                //Save the recipient so the success status, error message, and
                // sending time are saved.
                recipient.Save();
            }
        }
    }

I am trying to convert the CreateAndSendInvitation to vb.net rather than C#. All of my references are good after adding the checkbox.dll to my web solution. However, I'm getting errors with certain method calls. Here are my list of errors.

1.Dim rtData As DataSet = ResponseTemplateManager.GetAvailableResponseTempla tes("Form.Administer")

--------

Error 83 Overload resolution failed because no accessible 'GetAvailableResponseTemplates' accepts this number of arguments.

2. invitation.Save()

---------

Error 84 Argument not specified for parameter 'principal' of 'Public Sub Save(principal As Prezza.Framework.Security.Principal.ExtendedPrinci pal)'.

3. EmailListPanel.GetAvailableEmailLists()

----------

Error 85 Overload resolution failed because no accessible 'GetAvailableEmailLists' accepts this number of arguments.

4. Dim userGroups As Group() = Group.GetGroups(PermissionJoin.Any, "Group.View")

----------

Error 86 Value of type 'Checkbox.Security.PermissionJoin' cannot be converted to 'Prezza.Framework.Security.Principal.ExtendedPrinc ipal'.

[pwiesner]

It looks like this example is somewhat out of date. The signatures of a few key methods were changed in order to accommodate the development of the invitation management web service.


Error 83 Overload resolution failed because no accessible 'GetAvailableResponseTemplates' accepts this number of arguments.

Gets a of ResponseTemplates available to the logged-in user.

The paging size for the returned table.
The page number to return
A field to filter by.
A string to search the filter field on.
A field to sort by.
bool; whether to sort descending or not.
Permissions to check for access to ResponseTemplates.
A containing one table.

In order to disable either pageSize or the page you can pass -1.
In order to disable filtering you can pass null.
In order to disable sorting you can pass null.

An example that will produce the same results as the deprecated method is below:
DataSet ds = ResponseTemplateManager.GetAvailableResponseTempla tes(-1, -1, null, null, null, false, permission);



Error 85 Overload resolution failed because no accessible 'GetAvailableEmailLists' accepts this number of arguments.

3. EmailListPanel.GetAvailableEmailLists()

///

/// Gets all EmailLists available for use by the principal.
///

/// Principal accessing list
/// a list of EmailLists available for use by the principal.
public static DataSet GetAvailableEmailLists(ExtendedPrincipal principal)



Error 86 Value of type 'Checkbox.Security.PermissionJoin' cannot be converted to 'Prezza.Framework.Security.Principal.ExtendedPrinc ipal'.

///

/// Get an of group objects whether principal has
/// the specified permissions.
///

/// Principal accessing list
/// When multiple permissions are specified, this parameter allows
/// the caller to specify whether all or any of the permissions must be met.
/// Permissions to check against group access lists and default policies.
/// of user groups.
public static Group[] GetGroups(ExtendedPrincipal currentPrincipal, PermissionJoin permissionJoinType, params string[] permissions)