Tutorial: Instalar workflows no Sharepoint programaticamente

Neste post pretendo apresentar como “instalar” um workflow declarativo (como os workflows criados no Sharepoint Designer) no Sharepoint programaticamente. Os testes que fiz de instalação foram feitos no Sharepoint Foundation 2010, porém acredito que se aplicam ao Windows Sharepoint Services 3.0 e também ao Microsoft Office Sharepoint Server 2007.

Arquivos que compõe o workflow declarativo

Primeiramente, para instalar o worflow no Sharepoint, é necessário ter os seguintesarquivos:

1. Desenho do workflow. (obrigatório)
   Este arquivo possui extensão XOML. É um xml que onde estão declarados os passose as ações do workflow.
2. Configurações do workflow. (obrigatório)
   Este arquivo normalmente possui o mesmo nome do arquivo XOML, porém com o seguintesufixo: wfconfig.xml, por exemplo, se seu XOML se chama MeuWorkflow.xoml, este arquivose chamaria MeuWorkflow.xoml. wfconfig.xml
3. Formulário de abertura do workflow. (opcional)
   Este é um arquivo aspx, com o formulário de abertura do workflow. Usado em workflowspossuem a opção de serem iniciados manualmente.
4. Arquivo Rules. (opcional)
   Este arquivo contem um XML com regras e possui extensão .RULES. Estas regras sãoutilizadas como condições em IFs criados dentro do workflow.
5. Arquivo [Content_Types].xml (opcional)
   Este arquivo possui exatamente este nome e nele podem ser incluídos content typesque serão utilizados nas tarefas do workflow. Lembre-se que se você irá criar tarefascom content types, estes deverão sempre herdar do content type “Workflow Task”.

Instalação do workflow

A instalação do workflow no Sharepoint é dividida em três passos. Parecem simples,porém existem alguns detalhes muito importantes que se não observados podem gerarmuita dor de cabeça, pois se não seguidos, o workflow não será instalado ou atualizadoe o Sharepoint não dará nenhuma pista do que pode estar ocorrendo. Os três passossão:

1. Upload dos arquivos do workflow no Sharepoint;
2. Validação dos XMLs e criação dos objetos necessários;
3. Criação ou atualização do workflow.

A seguir estão os detalhes de como fazer cada passo:

Upload dos arquivos do workflow no Sharepoint

Os arquivos dos workflows declarativos ficam armazenados numa biblioteca específicano Sharepoint. Esta biblioteca não pode ser visualizada pela interface do Sharepoint,porém é possível ver os arquivos que estão lá através do Windows Explorer. Se vocêdigitar “\\[endereco _sharepoint]\Workflows” verá as pastas e arquivos dos workflowsinstalados no Sharepoint.

Por algum motivo, o Sharepoint não consegue ler o arquivo do workflow se ele é inseridopela forma habitual, usando o SPWeb.Files.Add(). Portanto, devemos utilizar a interfaceFrontPage RPC, a mesma que o Sharepoint Designer utiliza para enviar os arquivosdo workflow criados dentro dele. Como o código para isso é muito complexo e nãofui eu que criei (ele está disponível na internet em diversos blogs), não colocareino corpo deste post. Porém você pode baixá-lo no exemplo anexo a este post. A classeDocLibHelper é a classe responsável pelo upload utilizando o FrontPage RPC.

Validação dos XMLs e criação dos objetos necessários

O Sharepoint expõe um serviço com métodos para a validação e instalação dos workflows.Estes métodos fazem parte do serviço WebPartPages. Portanto, será necessário adicionaruma Service Reference no projeto apontando para o seguinte endereço: http://[endereço_sharepoint]/_vti_bin/Webpartpages.asmx

O método utilizado para a validação e criação dos objetos é o ValidateWorkflowMarkupAndCreateSupportObjects

O serviço precisa ser executado utilizando um usuário com permissão administrativano site no qual o workflow será instalado. Este método retorna uma string, na qualserá retornado um XML com uma mensagem de sucesso, caso esteja tudo OK com o mark-updo workflow, ou com mensagens de erro apontando problemas no mark-up. O código parachamar o serviço ficará assim:

string response;
WebPartPages.WebPartPagesWebServiceSoapClient service = new WebPartPages.WebPartPagesWebServiceSoapClient();
service.ClientCredentials.Windows.ClientCredential = CredentialCache.DefaultNetworkCredentials;
service.ClientCredentials.Windows.AllowedImpersonationLevel = System.Security.Principal.TokenImpersonationLevel.Impersonation;

response = service.ValidateWorkflowMarkupAndCreateSupportObjects(xomlMarkup, null, configMarkup, "2");

Analisando o código, podemos observer que:

• Primeiro instanciamos o serviço e atribuímos uma credencial de usuário. No caso,o usuário que está executando o programa.
• A variável xomlMarkup é uma string com o XOML do workflow que será instalado.
• O parâmetro null seria uma string com o mark-up do arquivo RULES. Como neste exemplonão temos nenhum IF no workflow, não precisamos deste arquivo.
• O parâmetro configMarkup é uma string com o XML de configurações do workflow.
• O último parâmetro que o método espera identifica se queremos apenas validar o workflowou validar e criar os objetos dos quais o workflow poderá depender (como site columns,contente types ou outros). “1” significa apenas validar. “2” significa validar ecriar os objetos.

Criação ou atualização do workflow

O próximo passo é instruir o Sharepoint a instalar o workflow. O serviço WebPartPagestem outro método para isso: AssociateWorkflowMarkup Assim como o método anterior,ele retorna uma string com um XML que possui mensagens de erro ou o GUID do workflowcriado, caso a instalação seja feita com sucesso. O código ficará assim:

string response;
WebPartPages.WebPartPagesWebServiceSoapClient service = new WebPartPages.WebPartPagesWebServiceSoapClient();
service.ClientCredentials.Windows.ClientCredential = CredentialCache.DefaultNetworkCredentials;
service.ClientCredentials.Windows.AllowedImpersonationLevel = System.Security.Principal.TokenImpersonationLevel.Impersonation;

response = service.AssociateWorkflowMarkup("Workflows/Teste-Deploy-By-Code/Teste-Deploy-By-Code.xoml.wfconfig.xml", version);

Analisando o código, podemos observar:

• O primeiro parâmetro é o caminho relativo ao site do arquivo de configuração doworkflow.
• O segundo parâmetro é a versão do arquivo e é muito importante. Caso a versão doarquivo não seja passada corretamente, o workflow não será instalado, o método dowebservice dará erro e não gerará nenhuma linha no log. Passei muito tempo paradescobrir que eu tinha problemas nessa parte do código, porque tive até que usaro reflector e debugar a DLL do Sharepoint para entender qual era o problema. Olhandoo exemplo completo anexo ao post, você poderá ver como pode ser tratado este detalheda versão.
• Importante: Dentro do arquivo de configuração (wfconfig.xml) há uma referência parao arquivo XOML, e alí também há uma configuração de versão, que deve bater com aversão do arquivo XOML.
• Todas essas strings de versão são sempre no formato VX.X, exemplo: V1.0, V2.0, etc.

Recapitulando os pontos mais críticos:

Os pontos nos quais tive dificuldade de resolver e que para tal gastei mais tempoforam os seguintes:

• Precisamos usar o FrontPage RPC para enviar os arquivos do workflow para o Sharepoint.Tentei outras duas formas de subir arquivos no Sharepoint e o serviço WebPartPagesnão conseguiu ler os arquivos do workflow em nenhuma delas.
• O Sharepoint versiona os arquivos automaticamente, e precisamos passar a versãocorreta do arquivo que será utilizada pelo serviço. Isso vale para o parâmetro dométodo AssociateWorkflowMarkup e para as referências no arquivo wfconfig.xml, comoXomlVersion, por exemplo.
• O formato dessas strings de versão é VX.X, se a versão for passada em outro formato,o serviço WebPartPages vai dar erro.

Abaixo você pode baixar uma aplicação console que fiz de teste, que pode ser usadacomo exemplo. Nela eu instalo um workflow simples no Sharepoint. Este workflow apenastem uma atividade que muda o seu próprio status para a string “Terminou :)”. Paratestar este exemplo no seu próprio Sharepoint, você deverá alterar a linha 3 doarquivo “Teste-Deploy-By-Code.xoml.wfconfig.xml”, você deverá colocar o ID de umalista que exista no seu Sharepoint, o workflow de teste será associado à esta lista.

Baixar código de exemplo