Claims Auth with K2 Windows STS

There are times when you need to provided a dedicated login page to your K2 smartforms Forms or even embed the K2 smartforms Form into your custom ASP.NET website (iFrame). The main issue with these approaches is that K2 smartforms uses Claims Authentication with its K2 Windows STS and thus your users may need to log into your custom ASP.NET website, then log into K2 again, which is not a pretty solution.

This article will show you how to configure your ASP.NET website to authenticate against K2 Windows STS for a seamless login experience.

Note: This procedure is for integration with K2 Windows STS Issuer only. To integrate with K2 Forms STS requires additional work, which will be discussed in a future post.

Add Site Realm and Audience information to K2

  1. Log into K2 Designer and navigate to the Manage Site Realms Form. (All Items > System > Management > Security > Forms > Manage Site Realms)

    140-manage_site_realms
    Path to Manage Site Realms Form
  2. Run the Form.

    140-Run_Form
    Run the Manage Site Realms Form
  3. Click on the New button under the Realms section.

    140-New_Realm
    Add a new Realm
  4. Fill in the URI, Reply URI and select K2 Windows STS for Linked Issuers. Click OK.
    140-New_Realm_Details
    New Realm details
      • URI: This is the IIS website URL for your ASP.NET Web Application. If it is a sub-site, e.g. K2/CustomSite, then you will need to include the full URL path e.g. http://k2blackpearl.somewhere.com/CustomSite/
      • Reply URI: This is the URL that will be called by K2 Issuer. If your site is the root IIS website, then pass in a “/”. If it’s a sub-site, e.g. K2/CustomSite, pass in the sub-site path will do. e.g. “/CustomSite/“.
      • Home Realm: No idea yet. This is something I’ll need to find out more.
      • Linked Issuers: We are authenticating with K2 Windows STS, so obvious choice to choose (=

    IMPORTANT: For both URI and Reply URI, the trailing forward-slash (/) is very important. In earlier versions of K2 blackpearl, the slash is assumed to be always present and thus will throw a “Index and length must refer to a location within the string.” error.

  5. Leave the K2 Designer open for now.

IIS Website Application Pool

Make sure your website’s Application Pool is running .NET Framework v4.0 and Managed Pipeline Mode = Integrated.

Visual Studio Web Application Configuration

Update Web Application’s Web.Config

Download and copy WindowsSTS_web.config to your website’s web.config file. Run through the following sub sections to update the config file.

Update WindowsSTS Thumbprint value
  1. Go back to K2 Designer, navigate to and run the Manager Issuers Form.  (All Items > System > Management > Security > Forms > Manage Issuers).

    140-manage_issuer
    Path to Manage Issuers Form
  2. On the Form, copy the Thumbprint value for K2 WindowsSTS record. The Use For Login value should be True here, since we are going to authenticate with it.

    140-manage_issuer_thumbprint
    Getting K2 WindowsSTS Thumbprint
  3. Open the web.config file updated earlier and change the thumbprint attribute value on the path configuration / system.identityModel / issuerNameRegistry / authorithy / keys / add.

    140-WindowsSTS_Thumbprint
    Updating WindowsSTS thumbprint value
  4. Save the web.config file. Leave the K2 Designer open. You will need to make use of this form again in the next section.
Update Federation Configuration

In the web.config file, go to the section configuration / system.identityModel.services / federationConfiguration.

If your K2 smartforms is configured for HTTPS protocol, you will need to update the requireSsl and requireHttps attributes to true.

140-SSL_Flags
SSL/HTTPS flags

Next, you will need to update the issuer, realm and reply attribute values and save the web.config file.

140-issuer_realm_reply
Issuer, Realm and Reply attributes

 

  • issuer: This is your K2 WindowsSTS issuer URL. Go back to your K2 Designer Manager Issuer Form that was opened earlier to copy the URL.

    140-Issuer_URL
    Edit this record to copy the URL easily
  • realm: This is the website URL used when you add the Realm to K2 in the earlier part of this article. In my example, my URL will be http://K2WindowsSTSLogin.domain.com/.
  • reply: This is the reply uri added earlier in this exercise. Important thing to note here is that the full URL is required. So meaning if it not replying to a sub-site, then the URL will be http://K2WindowsSTSLogin.domain.com/. If it is replying to the sub-site named “/site1”, then the URL will be http://K2WindowsSTSLogin.domain.com/site1/.

Note:

  • It is important that the trailing forward slash (/) is included for both the realm and reply attribute values. If not, you will get the error “Index and length must refer to a location within the string.” when your run the authentication later.
  • There should not be a trailing forward slash (/) for the issuer attribute value.
  • Since the authentication will be looking up the issuer, realm and reply URL, make sure that the web server machine is able to resolve the domain name or NetBios name.

Adding assembly references to your website

You will need to add the following assemble references to your website.

  • System.IdentityModelGAC
  • System.IdentityModel.ServicesGAC
  • SourceCode.Security.WebC:\Program Files (x86)\K2 blackpearl\Host Server\bin\SourceCode.Security.Web.dll
  • SourceCode.Security.Claims.Web –  C:\Program Files (x86)\K2 blackpearl\Host Server\bin\SourceCode.Security.Claims.Web

Add a Global.asax for your website

Download and copy the file content (Global.asax) to your global.asax.cs. This file contains the codes to manage Federation Authentication issues. It is not the perfect set, but solves most of my issues.

Add something to test

Now, to test that the Claims Authentication works and the federation token is recognized by K2, we need a test page.

In our test, let’s create a default.aspx WebForm and add a response.redirect method in the Page_Load method to go to your K2 Designer URL.

140-Page_Load_redirect
Default.aspx Page_Load method

Grand Finale – Testing Claims Auth with K2 Windows STS

Now, to run the test, publish your Web Application to IIS, open your web browser and navigate to your custom website. When the site loads, you will notice that it is redirected to your K2 WindowsSTS for authentication.

140-login-prompt
Redirect to K2 Windows STS for authentication

Go ahead to fill in the user name and password to login. You will notice that the authentication will be successfully and redirected to your reply uri. Your default.aspx page will be loaded and redirect to your K2 Designer site. There is no additional login at your K2 Designer site and it loads your credentials correctly!

140-K2_designer
K2 Designer logged in with your account credentials!

 

Have fun!

 

Troubleshooting

No connection could be made because target machine actively refuse it 127.0.0.1:5555

This error will occur when you have a distributed setup – blackpearl and smartforms server on different boxes.

Error on distributed setup.
Error on distributed setup.

To resolve this, make sure you have the HostName key in your ASP.NET web.config’s appSettings section. This key’s value should be your K2 blackpearl server/cluster’s FQDN.

140-hostnamefqdn
HostName key

Carry out an IIS reset and everything should work now.

K2 smartforms: CSS hack to rotate Data Label text

Do you want to have a section title that looks like this?

134-Outcome
Left rotated section title

If you do, this is the CSS hack/trick to make it happen:

  1. Add the following style to your selected Theme’s CSS file.
  2. Next, in your View or Form, add a Label and fill in the Text as “rotate-left”. Notice that this is the value of the title attribute of the style above.

    134-Label_property
    Set Label’s Text property to “rotate-left”
  3. Add a Data Label right after Label configured above. There’s no special settings for this control.

    134-DataLabel_after_Label
    Data Label right after the Label with “Title” = “rotate-left”
  4. Restart your IIS if required and test the Form and the Data Label‘s text will be rotated.

    134-Outcome
    Final Outcome

Using K2 Workflow Client API

[Updated: 4/6/2015]: Added reference to usage of WorklistCriteria here.

The SourceCode.Workflow.Client assembly provides the access to interact with the K2 blackpearl Server in the context of a User. This means that the API will not be able to query, for example, for all Users who has a Worklist Item from a specific Process. You will need to use SourceCode.Workflow.Management assembly for this. This API, however will allow the current User to impersonate as any other User within K2, if the account has the Impersonate rights on the Workflow Server. We will see more about this. Now down to the basics.


K2 Workflow Client API

Adding a reference to the assembly
  1. SourceCode.Workflow.Client
  2. SourceCode.Hosting.Client

These 2 assemblies can be found in the following location:

  • GAC – This is if you are working from within the K2 sever
  • K2 blackpearl’s bin folder – If you have the client components installed on your machine. The default path is C:\Program Files (x86)\K2 blackpearl\bin.
  • K2 Host Server’s bin folder – If you are working from within the K2 server. The default path is C:\Program Files (x86)\K2 blackpearl\Host Server\bin.

Note: The API call is carried out via RPC, so it means that as long as you have the required DLLs with your application, you will be able to make the call even if you did not install the K2 Client Components on that machine.


 

Open a connection to K2 blackpearl server

To open a connection, you only need the following:

For the Open method, there are a couple of variations:

  • Open(string Server): This requires a server name that can be resolved by the DNS/Host File or an IP.
  • Open(string Server, string ConStr): The 2nd parameter provides a connection string information. See ConnectionSetup.ConnectionString property.
  • Open(ConnectionSetup setup): This requires a ConnectionSetup object. You can provide a different log in credentials here.

 

User Property

Once the connection is opened, the User property will show the current logged on account:

111-User_Property
Connection object’s User property

If you find that the User property does not match the current logged on User in your ASP.NET page, it means that your web.config file is not configured to impersonate the current logged on User. Make sure the following is present in your web.config file:


 

Impersonate another User

If the current logged on User has the Impersonate rights on the Workflow Server:

You can execute the following code to impersonate as any User within the K2 environment:


 

Closing a connection to K2 blackpearl server

When you are done with the connection, always remember to close it by calling on the Close or Dispose method. You should always wrap the connection in a Using block:

Or a try-catch and/or finally block:


 

Start a Process Instance

To start a new process instance (a.k.a new workflow instance),  you will need to create a ProcessInstance object first.

The path to process is a combination of the root project folder name, followed by any folders’ name till the process. So in the following example:

111-Project_process_path
K2 Designer for Visual Studio

111-Workspace_Process_path
K2 Workspace

The path will be “TestProject1\ModuleA\Process1”.

With the ProcessInstance object created, you will be able to update the Folio and process level Data Fields before the process instance starts. This procedure is optional.

When the necessary updates on the ProcessInstance object is completed, you will need the Connection object’s StartProcessInstance method call to kick start the process instance.

Note: The StartProcessInstance method runs asynchronously by default. If you need the method to be executed synchronously, pass a 2nd parameter “true”:


 

Opening a Worklist

A work list (task list) is a collection of work list items (task list items) that is assigned to the current logged on user. You need to call on the OpenWorklist method of the Connection object and it will return a Worklist object, which is a collection of WorklistItems. The following is a sample method call:

Note: The OpenWorklist method without any input parameter will return the entire collection of WorklistItems of the current User. This is not going to be efficient and very time consuming if the current User has thousands of tasks. To overcome this, we should use a Filter with the OpenWorklist method, which we will discuss in a separate article you can find here. [Updated: 4/6/2015]


 

Open WorklistItem

Now, the WorklistItem is a single task assigned to the current User. It has the information of the current process instance and also the Activity Destination Instance. This means that we can draw the following information from it (Just to name a few):

  • WorklistItem.ProcessInstance.Folio: The Folio of the current process instance.
  • WorklistItem.ProcessInstance.DataField[“myField”].Value: Get the process level data field.
  • WorklistItem.Data: The full URL of the task form.
  • WorklistItem.Actions: The configured Actions for this task.

To open a work list item, it means getting K2 to assign a slot to this user. This method will also validate if the current user is the valid Destination User and whether the work list item is still available for actioning.

SN stands for Serial Number, which is an identifier that the K2 server will insert as a query string parameter with the task form URL.

Just for information, the serial number comprises of:

  • Process Instance Id; and
  • Activity Destination Instance Id

The 2 values will be separated by an underscore ‘_’ symbol. For example: SN=123_45


 

Execution the work list item action

And of course, with the WorklistItem, you will be able to execute the configured Action (i.e. when User clicks on the Approve button).

Note: The action name needs to be spelled exactly the same as configured in the process.

Note: The Execute method runs asynchronously by default. If you need the method to be executed synchronously, pass a 2nd parameter “true”.


Samples

Here are some “more complete” sample codes if you are still unclear:

Start a new process instance

Open work list

Open work list Item

Execute an action


 

Have fun!!

 

K2 blackpearl: Why my workflow escalation did not kick off after X working days??

If you have Working Hours configured, for example, Mon-Friday, 8 working hours

102-Working_Hours_Config
Working Hours configured

And in your workflow, you configured an Escalation using the Escalate After template and filled in the Days value. For example, 3 days:

102-Escalation_after_3_days
Escalate After template configured with Days = “3”

 

Your workflow WILL NOT be kicking off the escalation after 3 working days. It seems logical from the configurations, but it is not!

In the back-end, Escalation will convert Days to Hours, meaning 3 days x 24 hours = 72 hours. This will be the number of hours the Escalation is waiting for. When paired with Working Hours (8 hours working day in our example), the final escalation date will be 9 days later ( 72 hours / 8 hours = 9 days). This is how it works!

So, if you are using Escalation with Working Hours, always remember that Days will be converted to Hours to get the final escalation date. Hope it helps!

K2 blackpearl: How to debug your Default Server Event (Codes) in Visual Studio 2013

There are times when you need to write codes in your K2 workflow to provide features that is not available out-of-box. It could be a complex logic processing, sending of formatted HTML email with table contents, etc. In this article, I’m going to show you how to attach to the K2HostServer.exe process to debug your workflow.

Pre-requisite

  1. In your Visual Studio, open the Options dialog (Tools > Options).

    87-VS_Options_Menu
    Tools > Options
  2. In the Options dialog, select the debugging category and uncheck the option, “Require source files to exactly match the original version” and click OK.
    87-Remove_debug_option
    Uncheck “Require source files to exactly match the original version”

     

Attaching to the K2HostServer.exe process

  1. Deploy your K2 process, if you have not done so.
  2. Open your process in Visual Studio.
  3. Right click on your Default Server Events (Codes), select View Code, followed by Event Item to view the codes.

    87-View_code
    Default Server Event (Codes) > View Code > Event Item
  4. Add a breakpoint.

    87-break_point
    Add a break point in your codes.
  5. In the menu, select DEBUG > Attach to process…

    87-Attach_process
    DEBUG > Attach to Process…
  6. In the Attach to Process dialog, select K2HostServer.exe under Available Processes. You may need to check the “Show processes from all users” if you are not logged in as the K2 Service account.

    87-select_K2HostServer.exe
    Select K2HostServer.exe process
  7. Next, click on the Select… button.

    87-attach_select_btn
    Click on the Select… button
  8. In the Select Code type dialog, select Debug these codes types radio button and check Managed (v4.5, v4.0) and click OK.

    87-select_code_type
    Select Managed (v4.5, v4.0)
  9. Click on the Attach button and we are ready to test the workflow!
    87-Ready_to_attach
    Attach!!

    Note: Don’t worry if the symbols are not loaded after you attached to the process. It will do so when the workflow kicks off.

 

Debugging

Start your workflow running and wait for the breakpoint to hit. When it does, it is up to your debugging skills to find your problem now =)

87-debugging
Time to debug!

Just a side note, if you are running the K2 blackpearl Server service in console mode, your Console.WriteLines will appear in the console too.

87-output_in_console
Console.WriteLine shown in K2 blackpearl Server console

 

Happy Debugging!

Checking for inactivity in K2 Smartform

This article covers the steps to get a timer going that checks for inactivity.

Inactivity is consider as no movement in the mouse or keyboard.


So here we have create a View and add a Data Label in it.

Step 1, adding a Data Label
Step 1, adding a Data Label

 

Next go to the rules designer and add a View Initialize Rule.

2. Adding a View Init Rule
Step 2. Adding a View Initialize Rule

Now configure this rule and do a “Transfer Data” action.

3. Adding Transfer Data Action
Step 3. Adding a Transfer Data Action

The javascript that does all the magic is found here, http://stackoverflow.com/questions/9564602/how-to-know-browser-idle-time

But for our case, we need to modify it a little, so to use my version download the script from the following link, http://pastebin.com/embed_js.php?i=FDkg3EML

4. Adding the script
Step 4. Copy the script into the rule

 

Finally, Save & Checkin and Test.

Step 5. Testing!
Step 5. Testing!

K2 smartforms: How does “Get confirmation from user” Action functions

A lot of times before a form submission, changes to important values, etc. “Initialize” actions, you will want to prompt the User to get their confirmation on their action like the following:

Some weird logic.. =)
Some weird logic.. =)

Well.. The above is just for illustration and by no means you should irritate your Users, no matter how you dislike them =)

The Action that allow us to prompt and get a confirmation from the User is the “Get a confirmation from user” Action, which can cheap mlb jerseys be found under the “Notifications” section:

Where is the Action?
“Get confirmation from user” smartforms: Action

Now, based on the explanation from the production site the “OK” and “Cancel” buttons function like this:

  1. If the “OK” button is clicked, it will process the subsequent Actions.

    62-ActionsAfterGetConfirmation
    Click “OK” and the highlighted cheap mlb jerseys section will be processed.
  2. If the “Cancel” button it clicked, it will stop processing subsequent Actions.

    62-ActionsAfterGetConfirmation
    Click “Cancel” and the highlighted section will NOT be processed.
  3. When the Action is used in a “If” to condition, clicking on the “OK” button will process the subsequent Actions. Click on the “Cancel” button will process the “Else” condition.

    62-ActionInCond
    How the Action reacts to “OK” and “Cancel” clicks

It is pretty straight cheap mlb jerseys forward for the above cases, but it is different if Nullam you configure it like the following:

62-FailCond
Wrong configuration

In the sample, message B or C will still be processed after the user clicks on “Cancel” button. This is correct by design, since the production documentation states that it will only stop execution of follow-up Actions. So, an “If” is not an Action and thus will be processed regardless of the button clicked.

To make the above sample work, you will need to wrap Mac the Action within a Condition like the following:

62-CorrectConfig
Correct configuration

This setup will ensure that when the User clicks on the “Cancel” button, the “Stop rule execution” Action is triggered and the rest of the Rule processing is aborted. If the User clicks on the “OK” button, the follow-up Actions and Conditions will be processed.

Now, what did I put in the “If an advanced condition is true” Condition?

62-advCond
To ensure this condition always run.

It is a 1 cheap mlb jerseys = 1 condition which will ensure that it will always execute and support our “Get confirmation from user” scenario.

Hope this helps!

K2 smartforms: View’s Expressions need “Initialize” Rule to start on Form load

When you Nouvelle add a View to a Form, wholesale nfl jerseys the Form will automatically inherit the Rules from the View and at the same time, automatically adds a “When [View] executed Initialize” Rule. This is regardless whether your View has this Rule at all.

Based on K2 smartforms Implementation Tips, you should “Refactor, clean and simplify Form and View Rules” to speed up development and runtime experience.

Now, this tip is only true if you do not need any Expressions on the View to be evaluated when the Form loads.

Let’s see why:

This is my sample View:

View Design
View Design

It has 2 Text Boxes, let us refer to the top Text Box as “Value A” and the bottom Text Box as “Value B”. Lastly, there is a “Addition Result” Data Label, Or which has the following Expression:

Addition Result Data Label's Expression
Addition Result Data Label’s Expression

When I test this View, I should see that the “Additional Result” gets evaluated correctly.

View in run time mode
View in run time wholesale nfl jerseys mode

Next, I proceed to add the View to a Form.

Form with the View added
Form with the View added

Going on to the Rules page now, I see that there is a “When the Form is Initializing” Rule added.

Form Rule(s)
Form cheap jerseys Rule(s)

In the rule, there is an Action running the View’s “Initialize” method.

The Initialize Action
The Initialize Action

But wait! I did not configure any Initialize Rule on my View earlier. So let’s remove it based on the best practice and view my Form in runtime URL.

Form run time. Note that the "Addition Result" did not evaluate.
Form run time. Note that the “Addition Result” did not evaluate.

Hmm… something is wrong. The “Addition Result” Data Label did not show any value. It Wylick should have, since it has the Expression configured and both “Value A” and “Value B” Text Boxes have values in them.

Updating the “Value A” to 2 kicks off the Expression evaluation and I get the value in “Addition Result”. This shows that the Expression works, just that it did not start evaluating when the Form loads.

After updating "Value A", the "Addition Result" is evaluated now
After updating “Value A”, the “Addition Result” is evaluated now

Now, of going back to my Form Rule designing page, I put back the Form Initialization Rule that calls on the View’s Initialize method that with I have deleted earlier. After checking in the Form, I try running the Form again.

It works now!

Expression working now!
Expression working now!

Great! Now we know God that View’s Expressions will only start running on Form load when the View’s Initialize method is called on. So, it does not mean that we should always remove View Initialize method on Form Rules when there isn’t any actions in it =)

K2 smartforms: How to Create a selectable group of Views

This article wholesale MLB jerseys shows you how to create a selectable Checkbox Views section like the following:

Section collapsed
Section collapsed

 

Section expanded
Section expanded after checking on the section header’s checkbox

 

  1.  Appending the following style to your form’s theme CSS files (Both Designer and Girls Runtime).
    If you are using the default Platinum theme, then your CSS file will be located at [Path to K2 blackpearl folder]\K2 SmartForms Runtime\Styles\Themes\Platinum.css and [K2 blackpearl folder]\K2 smartforms Designer\Styles\Themes\Platinum.css.

  2. Edit the Form. Add a Table control to the form. Set the column and rows to be 1 x 1.

    Add Table control
  3. Add a Label control into the table cell. This label needs to be the first control in the table cell.

    Add Label control into the table cell
    Add Label control into the table cell
  4. Add a Checkbox control into the table cheap jerseys cell, right after the zum Label control above. The CSS selector above will use this These combination of Table > Label + sibling Checkbox condition to apply the required stylings.

    17-Add_Checkbox
    Add Checkbox control after the Label control
  5. The section header is now ready. Add your Views after this header and apply your rules to hide/show the underlying views when the checkbox Montaditos is checked or cleared.
    Add wholesale NBA jerseys required child Views

    Apply Rules to hide/show Views on Checkbox is changed
    Apply Rules to hide/show Views on Checkbox is changed
  6. Save and test the form!

    Final output
    Final output

Note: You may need to execute an IIS reset to refresh a cached stylesheet.

Adding Or Removing mysql from AutoStarting on Mac

The following snippet provide sample for adding the mysql service to cheap jerseys auto start on mac.

Note: You should input all these in the terminal cmd cheap jerseys China window.

Step 1 :

Step 2:

The following snippet kolejnego allow you Montreal to remove antes auto starting the mysql server.

Things to note here my manually removing this file from the LaunchAgents will not unload it!